Retain REST API Basics

Retain REST API follows RESTful design patterns and uses the following elements:

Schema and Objects - A schema is a collection of database objects. Each Retain object is comprised of attributes of different data types such as strings and integers, enumerations, and arrays. Retain objects are represented by a unique Vindicia identifier (VID). Many resources also provide an ID field for you to record your unique identifier which can contain any alphanumeric character but must not contain a forward slash /.
Operations and Endpoints - Vindicia Retain REST API uses standard HTTP verbs to request an operation. An operation requires one or more input arguments. The Retain REST API exposes key resources as endpoints that can be maintained using standard methods. A request call receives a response code, which indicates the success or failure of the API call and a description of the failure, when relevant.
Requests and Responses - As with standard APIs, Retain uses a request and response model. Each API request has an associated request identifier. You can find this value in the response headers, under Request ID. If you need to contact Vindicia about a specific request, providing the request identifier ensures the fastest possible resolution.
Interacting with Retain API

Interacting with Retain API

HTTP Verbs and Request Formats

As per RESTful design patterns, Retain REST API implements the following HTTP verbs:

Verb	Description
GET	Retrieve resources, either as a list or single record fetch
POST	Create new resources or update existing ones

For example:

Resources also have an object field that represents the resource type. See examples of requests and responses in RetainOpenAPIs chapter.

Request IDs

Each API request has an associated call identifier. You can find this value in the response headers, under Request-ID. If you need to contact us about a specific request, providing the request identifier ensures the fastest possible resolution.

Strings

All strings support up to 1,024 characters unless otherwise noted. Submitting values in excess of this limit will return an error.

Enumerable Values

Some fields, have a set of predefined values. Submitting any value other than those documented result in an error being returned with a status code of 400.

Arrays and Lists

The API returns multiple resources as list objects containing a JSON array. Additional data can be accessed through pagination. Example Response

{
      'object' : 'RETAIN',
      'id' : 'ret_1234',
      'items': [ {
        'object': 'RetainItem',
        'id': 'sub_1234.1',
        'product': {
            'object': 'Product',
            'id': 'prod_1234'
          }
        }, 
        {
          'object': 'RetainItem',
          'id': 'sub_1234.2',
          'product': {
          'object': 'Product',
          'id': 'prod_1235'
        }
      } 
    ]
    ... 
  }

Status Codes and Error Messages

Retain uses standard HTTP response codes to indicate the success or failure of an API request. In general:

Codes in the 2xx range indicate a successful response.
Codes in the 4xx range indicate an error that failed given the information provided by the client server. For example, a required parameter was omitted, a payment failed, etc.
Codes in the 5xx range indicate an error with Vindicia’s servers (these are rare).

Code	Status	Description
200	OK	Everything worked as expected.
207	Transaction Validation Error	An error message returned for each invalid submitted Transaction. The error provides the identifier of the Transaction, the Retain error code, and error message indicating the reason for the validation failure.Additionally, Retain also reviews the submitted Transactions in a post-submission system validation. These errors are then available as a csv file in the Retain Hub Submission History page or as Push Notifications. For troubleshooting input as well as more details of the submission error codes, see Retain Transaction Submission Errors.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	Couldn’t authenticate your request.
402	Authorization Failure	Authorization failed.
403	Forbidden	Authentication failed - check your username and password.
404	Not Found	The requested resource doesn’t exist.
429	Too Many Requests	Too many requests hit the API too quickly.
500	Internal Server Error	Server Error
503	Service Unavailable	We’re temporarily offline for maintenance. Please try again later.
When an error occurs, additional information is returned in the accompanying error message.

Error messages return an error object string, containing the following:

Attributes	Message
object	Value is Error
message	A human-readable message providing more detailed information about the error.

Basic HTTP response example

HTTP/1.1 200 OK
    Content-Type: application/json
    Content-Length: 150
    Request-Id: d837becba3325b62adddb2b0f1d7ab48824ff248
    Connection: close
    {
      'object' : 'Transaction',
        'id' : 'tx_1234',
        'vid' : '40f24148bdc282640b46ad281eec31f7dfd9202e',
          'created' : '2020-01-01T00:55:47Z'
    }

JSON error example

{
              'object': 'Error',
              'message': 'Invalid parameter: <bad_parm>.'
            }

Timestamps

All timestamps are represented in ISO 8601 format. Timestamps may be submitted in any timezone but are returned in UTC time standard.

Pagination

All GET endpoints that return an array (object list) support cursor-based pagination with pagination information inside a pagination object. This means that to get all objects, you need to paginate through the results by always using the id of the last resource in the list as a starting_after parameter for the next call. To make it easier, the API assigns the next call into next attribute, together with all the currently used pagination parameters. You know that you have paginated all the results when the return is empty and the next value is undefined. Using cursor-based pagination protects against the situation when the resulting object list changes during pagination (new resource gets added or removed). You can use limit, starting_after, and end_before parameters as needed to control pagination. The default limit is set to 20 but values up to 100 are permitted. Request Example

GET /foos
      Content-type: application/json
      Content-length: 32509

Collection Pagination Example

{
        'object': 'List',
        'data': [...],
        'total_count': 31,
        'url': '/foos',
        'next': '/foos?starting_after=Montly+Stream',
        'previous': '/foos?ending_before=Daily+Stream'
      }

Home

Guides

Interacting with Retain API

HTTP Verbs and Request Formats

Request IDs

Strings

Enumerable Values

Arrays and Lists

Status Codes and Error Messages

Timestamps

​Interacting with Retain API

​HTTP Verbs and Request Formats

​Request IDs

​Strings

​Enumerable Values

​Arrays and Lists

​Status Codes and Error Messages

​Timestamps

​Pagination

Interacting with Retain API

HTTP Verbs and Request Formats

Request IDs

Strings

Enumerable Values

Arrays and Lists

Status Codes and Error Messages

Timestamps

Pagination