Get Started with APIs

You can integrate with Prime Trust solutions using a RESTful API.

  1. Create a user.
  2. Create a JWT with your user.
  3. Call the authenticated APIs.

Sandbox and production environments

A sandbox environment is provided to you for testing. Some endpoints are specific to sandbox environment only.

EnvironmentURL
Sandboxhttps://sandbox.primetrust.com
Productionhttps://api.primetrust.com

This document uses paths relative to those hosts.

Standard responses

API responses will always return only one status code. While the JSONAPI spec does have examples of mixed errors, our API does not use them.

  • 200: No errors.
  • 201: No errors, created. (Used for special actions)
  • 202: No errors, accepted but no current response.
    • A Location header will tell you where the resource can be found when your request completes processing.
  • 204: No errors, no data to return. Common on DELETE requests.
  • 400: Request malformed, usually from a bad query string or form parameter.
  • 401: Not authenticated.
  • 403: Forbidden (you're authenticated but lack permission).
  • 404: Not found. The API route doesn't exist.
  • 405: Method not allowed. The method is not allowed on this API route.
  • 422: JSON body didn't validate properly.
    • This error should always be returned related to JSON attributes and not to query string or form parameters except where specifically noted.
  • 500: Internal server error.

Endpoints

Endpoints are organized by resource types and most resource IDs are UUIDs, although there are a few occasions where natural string keys are used for enum-like resources (e.g. account-types). So, contacts can be found at /v2/contacts and a single contact can be found at /v2/contacts/:id. If related links are not specifically provided in relationships, the location of related resources can be inferred accordingly.

Index Requests

In addition to the include, which all endpoints that return a payload support, index requests can also be paginated, sorted and filtered.

Includes

Allows for the inclusion of other related resources on the same API call with the keyword include. For example:

GET v2/contacts?include=cip-check

Pagination

The parameter page is used for pagination. page[number] indicates the page number and page[size] is the maximum number or resources returned. These default respectively to 1 and 25.

All applicable links are provided in links: first, last, next, and prev.

Additionally, meta properties are returned to indicate totals. page-count is the total number of pages and resource-count is the total number of resources.

For example, to get the 4th page and show 50 resources per page, you would append the following parameters to your URL:

?page[number]=4&page[size]=50

Sorting

The parameter sort is used for sorting how resources are returned. The value should be a comma-separated list of attribute names.

Resources can be sorted both by their own attributes or on the attributes of their respective relationships using a dot (.) to separate the relationship name and the attributes. A minus (-) is used for sorting in descending order.

For example, if you wanted to sort a contact by their primary street address and then name in descending order you would use the following:

?sort=primary-address.street-1,-name

Note specifically that you do not prefix attribute names on the current resource and you use the relationship name, not the resource type, for sorting relationships (e.g primary-address is used, not addresses which is the resource type of the primary-address relationship). Nested sorts are only available for resources immediately related to the current resource. You cannot, for instance, sort with an attribute like: account.owner.primary-address.country.

Filtering and querying

Filtering can be applied on GET calls for certain endpoints so you receive back only the information you require in the response body.

Filtering Rules

note

It's important to note that you can't filter by every column. Right now if you try to filter or sort by something that isn't allowed, the filter or sort is silently ignored or, in the case of bad data (like a number for a date field) you'll get a 500.

Attributes on which filtering is available are listed in API Reference Documention for each endpoint.

Here are the current operators:

OperatorDescription
eqEquals (exact match). Used when no operator is specified.
gtGreater than.
gteGreater than or equal to.
inAny item is an exact match. Takes special syntax, so if you wanted something where a status was one of a few, you would pass ?filter[status in]=pending,processing.
likeCase insensitive search. Does NOT support wildcards as of right now.
ltLess than.
lteLess than or equal to.
neqNOT equal.
ninNOT in.
nlikeNOT like.
swStarts with. Look for strings that being with filter value. Case insensitive.

Examples of Filtering

You pass a filter parameter that is the name of a field, potentially namespaced by a relationship, and optional operator (defaults to eq if none are given)

So, to filter contacts by names starting with j:

GET /v2/contacts?filter[name sw]=j

Filter contacts by account ID:

GET /v2/contacts?filter[account.id]=<account uuid>

Filter contacts by primary address in Nevada:

GET /v2/contacts?filter[primary-address.region]=NV`

There's also a special shorthand for filtering by id to make related links shorter. Contacts, again, by account ID:

GET /v2/contacts?account.id=<account uuid>`

Idempotent object creation

All POST API requests are checked for the presence of a X-Idempotent-ID header. The X-Idempotent-ID should contain a valid UUIDv4.

If the header exists but does not contain a valid UUIDv4, a 400 error is returned. If the header exists and contains a valid UUIDv4, one of two things can happen:

  • If this X-Idempotent-ID has already been used to successfully create/manipulate a resource in the past, then a 202 is returned with a Content-Location header that points to the resource.
  • If this X-Idempotent-ID has not already been used, then the API request is processed normally.

Note: In both cases there will be a X-Idempotent-ID header in the response which exactly matches the X-Idempotent-ID header in the request.

Example header

X-Idempotent-Id: 1cc2f3fe-e3aa-48d6-966b-9b8a61030dd0

Idempotent object creation V2

Idempotent requests have been improved to provide the original status code and response of a request regardless of outcome.

As with the first version of idempotency, When using the X-Idempotent-ID-V2 header the requested operation will only ever be executed on our system once as long as you send us the same UUID value on subsequent requests as you did on the first request.

However, V2 has the additional property that you will receive back the original response status code and response body every time you make the request. As soon as a response has been executed once, it will be returned to you on every subsequent request made with the same X-Idempotent-ID-V2` header value.

Example header

X-Idempotent-ID-V2: 1cc2f3fe-e3aa-48d6-966b-9b8a61030dd0

How to create a user

To make authenticated requests against the API you must start by creating a user with a name, email and password.

Request

POST v2/users
{
"data" : {
"type" : "user",
"attributes" : {
"email" : "{{user-email}}",
"name" : "{{user-name}}",
"password" : "{{password}}"
}
}
}

Response

{
"data": {
"type": "users",
"id": "a94128fa-187a-44ba-b2d0-a2a9bbf9988b",
"attributes": {
"claims": {},
"created-at": "2019-12-03T06:04:37Z",
"disabled": false,
"email": "example@primetrust.com",
"mfa-types": [],
"name": "Prime Trust Example",
"updated-at": "2019-12-03T06:04:37Z"
},
"links": {
"self": "/v2/users/a94128fa-187a-44ba-b2d0-a2a9bbf9988b"
},
"relationships": {
"user-groups": {
"links": {
"related": "/v2/user-groups?users.id=a94128fa-187a-44ba-b2d0-a2a9bbf9988b"
}
}
}
},
"included": []
}

Talk to your Sales Engineer to set up greater security around your user or users before moving into production.

The rest of the Prime Trust APIs endpoints uses JWTs as a bearer token for authentication. To create a JWT for a user you will need to use the user's email and password as basic auth.

How to create a JWT

Request

POST /auth/jwts

Response

{
"token": "eyJhbGciOiJIUzI1NiJ9.eyJhdXRoX3NlY3JldCI6ImUxNWFlNjZjLTI0NzgtNDE0NC1hNTM0LWJlOTRkNzI5MGUyOCIsInVzZXJfZ3JvdXBzIjpbXSwibm93IjoxNTc1MzUzMzUwLCJleHAiOjE1NzU5NTgxNTB9.C7honVy37VztObEofwPMn7XWus6r8VpYuSk8lXwlLYw"
}

Once you have created a JWT you are ready to interact with the rest of the Prime Trust API.

Last updated on