> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vindicia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](../topics/retainAPIRestBasics#)**

## Interacting with Retain API

**Parent topic:**[Retain REST API Basics](../topics/retainAPIRestBasics#)

### 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:

* GET [https://api.vindicia.com/retain/transactions/:id](https://api.vindicia.com/retain/transactions/:id)
* GET [https://api.vindicia.com/retain/transactions/:vid](https://api.vindicia.com/retain/transactions/:vid)

Resources also have an object field that represents the resource type.

See examples of requests and responses in [RetainOpenAPIs](/portal/apis/retain-api) 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](/portal/retainPortalUserGuide/topics/retainUploadHistoryTask) page or as [Push Notifications](/portal/retainImplementationGuide/topics/ProgGuide_PushNotifications). For troubleshooting input as well as more details of the submission error codes, see [Retain Transaction Submission Errors](retainErrorList#). |
| 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'
      }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.