NAV
CURL JAVA NODE PHP PYTHON OBJECTIVE-C RUBY .NET

Introduction

The Recroup API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients, and we support cross-origin resource sharing to allow you to interact securely with our API from a client-side web application (though you should remember that you should never expose your API keys or Access Token in any public website’s client-side code). JSON will be returned in all responses from the API, including errors (though if you’re using API bindings, we will convert the response to the appropriate language-specific object).

Authentication

You authenticate to the Recroup API by providing your access token in the request. You can manage your API credentials from your account. You can have multiple access tokens each associated with a different app, active at one time. Your API credentials carry many privileges, so be sure to keep them secret!

You can obtain an access token for your recroup account by creating an application from the developers dashboard and authorizing the acccount.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

Errors

Example Object

{
  "error": "not_found_error",
  "message": "the requested resource could not be found or doesn't exist"
}

Recroup uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing and etc.), and codes in the 5xx range indicate an error with Recroup’s servers.

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully, we return a 402 error code.

Error Description

Error HTTP Status Description
authorization_error 401 Access token is invalid or is expired/revoked!
invalid_parameter_error 400 A required parameter is missing or invalid
validation_error 400 Database validation for the POST / PUT request
failed_request_error 400 Request was valid but did not complete successfully
not_found_error 404 The requested resource was not found or doesn’t exist
endpoint_error 404 The endpoint of the request is not valid
payment_method_error 402 Payment method is missing or inactive
internal_server_error 500 There was a problem with recroup servers

Sample Requests

POST Request

Example Request

curl -X POST --include "https://api.recroup.com/v1/sample_requests" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  --data-binary '{"sample_parameter":"acme"}'
HttpResponse<JsonNode> response = Unirest.post("https://api.recroup.com/v1/sample_requests")
.header("Authorization", "Bearer <access_token>")
.header("Content-Type", "application/json")
.body("{\"sample_parameter\":\"acme\"}").asJson();
unirest.post("https://api.recroup.com/v1/sample_requests")
.header("Authorization", "<access_token>")
.header("Content-Type", "application/json")
.send("{'sample_parameter':'acme'}")
.end(function(result){
  console.log(result.status, result.headers, result.body);
});
<?php
$response = Unirest::post("https://api.recroup.com/v1/sample_requests",
  array(
    "Authorization" => "Bearer <access_token>",
    "Content-Type" => "application/json"
  ),
  json_encode(
    array("sample_parameter" => "acme")
  )
);
?>
response = unirest.post("https://api.recroup.com/v1/sample_requests",
  headers={
    "Authorization": "Bearer <access_token>",
    "Content-Type": "application/json"
  },
  params=json.dumps({"sample_parameter": "acme"})
)
NSDictionary *headers = @{@"Authorization": @"Bearer <access_token>", @"Content-Type": @"application/json"};
UNIUrlConnection *asyncConnection = [[UNIRest post:^(UNISimpleRequest *request) {
  [request setUrl:@"https://api.recroup.com/v1/sample_requests"];
  [request setHeaders:headers];
  [request setBody:@"{'sample_parameter':'acme'}"];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
  NSInteger code = response.code;
  NSDictionary *responseHeaders = response.headers;
  UNIJsonNode *body = response.body;
  NSData *rawBody = response.rawBody;
}];
response = Unirest.post "https://api.recroup.com/v1/sample_requests",
  headers:{
    "Authorization" => "Bearer <access_token>",
    "Content-Type" => "application/json"
  },
  parameters:{"sample_parameter" => "acme"}.to_json
Task<HttpResponse<MyClass>> response = Unirest.post("https://api.recroup.com/v1/sample_requests")
.header("Authorization", "Bearer <access_token>")
.header("Content-Type", "application/json")
.body("{\"sample_parameter\":\"acme\"}").asJson();

The above command returns JSON structured like this:

{
  "object": "sample_request",
  "id": "13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  "sample_parameter": "acme"
}

Creates a new sample_request object.

Endpoint

POST https://api.recroup.com/v1/sample_requests

Arguments

Parameter Description
sample_parameter optional - string
sample parameter

Returns

Returns a sample_request object if the call succeeded.

GET Request

Example Request

curl --get --include "https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json"
HttpResponse<JsonNode> response = Unirest.get("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31")
.header("Authorization", "Bearer <access_token>")
.header("Content-Type", "application/json")
.asJson();
unirest.get("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31")
.header("Authorization", "Bearer <access_token>")
.header("Content-Type", "application/json")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});
<?php
$response = Unirest::get("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  array(
    "Authorization" => "Bearer <access_token>",
    "Content-Type" => "application/json"
  )
);
?>
response = unirest.get("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  headers={
    "Authorization": "Bearer <access_token>",
    "Content-Type": "application/json"
  }
)
NSDictionary *headers = @{@"Authorization": @"Bearer <access_token>", @"Content-Type": @"application/json"};
UNIUrlConnection *asyncConnection = [[UNIRest get:^(UNISimpleRequest *request) {
  [request setUrl:@"https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31"];
  [request setHeaders:headers];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
  NSInteger code = response.code;
  NSDictionary *responseHeaders = response.headers;
  UNIJsonNode *body = response.body;
  NSData *rawBody = response.rawBody;
}];
response = Unirest.get "https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  headers:{
    "Authorization" => "Bearer <access_token>",
    "Content-Type" => "application/json"
  }
Task<HttpResponse<MyClass>> response = Unirest.get("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31")
.header("Authorization", "Bearer <access_token>")
.header("Content-Type", "application/json")
.asJson();

The above command returns JSON structured like this:

{
  "object": "sample_request",
  "id": "13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  "sample_parameter": "acme"
}

Retrieves the details of an existing sample_request object. You need only supply the unique sample_request identifier that was returned upon sample_request creation.

Endpoint

GET https://api.recroup.com/v1/sample_requests/{id}

Arguments

Parameter Description
id required - string
The unique identifier of the sample_request to be retrieved.

Returns

Returns a sample_request object if a valid identifier was provided.

PUT Request

Example Request

curl -X PUT --include "https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  --data-binary '{"sample_parameter":"acme"}'
HttpResponse<JsonNode> response = Unirest.put("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31")
.header("Authorization", "Bearer <access_token>")
.header("Content-Type", "application/json")
.body("{\"sample_parameter\":\"acme\"}").asJson();
unirest.put("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31")
.header("Authorization", "<access_token>")
.header("Content-Type", "application/json")
.send("{'sample_parameter':'acme'}")
.end(function(result){
  console.log(result.status, result.headers, result.body);
});
<?php
$response = Unirest::put("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  array(
    "Authorization" => "Bearer <access_token>",
    "Content-Type" => "application/json"
  ),
  json_encode(
    array("sample_parameter" => "acme")
  )
);
?>
response = unirest.put("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  headers={
    "Authorization": "Bearer <access_token>",
    "Content-Type": "application/json"
  },
  params=json.dumps({"sample_parameter": "acme"})
)
NSDictionary *headers = @{@"Authorization": @"Bearer <access_token>", @"Content-Type": @"application/json"};
UNIUrlConnection *asyncConnection = [[UNIRest put:^(UNISimpleRequest *request) {
  [request setUrl:@"https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31"];
  [request setHeaders:headers];
  [request setBody:@"{'sample_parameter':'acme'}"];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
  NSInteger code = response.code;
  NSDictionary *responseHeaders = response.headers;
  UNIJsonNode *body = response.body;
  NSData *rawBody = response.rawBody;
}];
response = Unirest.put "https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  headers:{
    "Authorization" => "Bearer <access_token>",
    "Content-Type" => "application/json"
  },
  parameters:{"sample_parameter" => "acme"}.to_json
Task<HttpResponse<MyClass>> response = Unirest.put("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31")
.header("Authorization", "Bearer <access_token>")
.header("Content-Type", "application/json")
.body("{\"sample_parameter\":\"acme\"}").asJson();

The above command returns JSON structured like this:

{
  "object": "sample_request",
  "id": "13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  "sample_parameter": "acme"
}

Updates an existing sample_request object.

Endpoint

PUT https://api.recroup.com/v1/sample_requests/{id}

Arguments

Parameter Description
id required - string
The unique identifier of the sample_request object to be updated.
sample_parameter optional - string
sample parameter

Returns

Returns the updated sample_request object if the call succeeded.

DELETE Request

Example Request

curl --delete --include "https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31" \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json"
HttpResponse<JsonNode> response = Unirest.delete("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31")
.header("Authorization", "Bearer <access_token>")
.header("Content-Type", "application/json")
.asJson();
unirest.delete("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31")
.header("Authorization", "Bearer <access_token>")
.header("Content-Type", "application/json")
.end(function (result) {
  console.log(result.status, result.headers, result.body);
});
<?php
$response = Unirest::delete("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  array(
    "Authorization" => "Bearer <access_token>",
    "Content-Type" => "application/json"
  )
);
?>
response = unirest.delete("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  headers={
    "Authorization": "Bearer <access_token>",
    "Content-Type": "application/json"
  }
)
NSDictionary *headers = @{@"Authorization": @"Bearer <access_token>", @"Content-Type": @"application/json"};
UNIUrlConnection *asyncConnection = [[UNIRest delete:^(UNISimpleRequest *request) {
  [request setUrl:@"https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31"];
  [request setHeaders:headers];
}] asJsonAsync:^(UNIHTTPJsonResponse *response, NSError *error) {
  NSInteger code = response.code;
  NSDictionary *responseHeaders = response.headers;
  UNIJsonNode *body = response.body;
  NSData *rawBody = response.rawBody;
}];
response = Unirest.delete "https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  headers:{
    "Authorization" => "Bearer <access_token>",
    "Content-Type" => "application/json"
  }
Task<HttpResponse<MyClass>> response = Unirest.delete("https://api.recroup.com/v1/sample_requests/13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31")
.header("Authorization", "Bearer <access_token>")
.header("Content-Type", "application/json")
.asJson();

The above command returns JSON structured like this:

{
  "object": "sample_request",
  "id": "13ed6883-34bc-4d0d-aa3d-7b70d4d1fc31",
  "deleted": true
}

Deletes an existing sample_request object.

Endpoint

DELETE https://api.recroup.com/v1/sample_requests/{id}

Arguments

Parameter Description
id required - string
The unique identifier of the sample_request object to be deleted.

Returns

Returns the id and deleted status of the sample_request object deleted.