Skip to main content

About JSON:API

Unit's API is REST-based and follows the JSON:API specification.

JSON:API specifies how a client should request resources to be fetched or modified, and how a server should respond to those requests. Resources in Unit include applications, customers, cards, accounts, transactions and more.

JSON:API is designed to minimize both the number of requests and the amount of data transmitted between clients and servers. This efficiency is achieved without compromising readability, flexibility, or discoverability.

JSON:API requires the use of the JSON:API media type (application/vnd.api+json) for exchanging data.

Request and Response Structure

All JSON:API requests and responses are JSON documents.

A document MUST contain one of the following top-level members:

  • data: the document's "primary data". Example: when creating an individual application resource, the primary data will contain the individual's personal information.
  • errors: an array of error objects.

Primary data MUST be either:

  • a single resource object for requests that target single resources, or
  • an array of resource objects for requests that target resource collections.
Single Resource Object Example:
    {
"data": {
"type": "individualCustomer",
"id": "1",
"attributes": {
// ... this customer's attributes
},
"relationships": {
// ... this customer's relationships
}
}
}
Array of Resource Objects Example:
    {
"data": [
{
"type": "individualCustomer",
"id": "1",
"attributes": {
// ... this customer's attributes
},
"relationships": {
// ... this customer's relationships
}
}, {
"type": "businessCustomer",
"id": "2",
"attributes": {
// ... this customer's attributes
},
"relationships": {
// ... this customer's relationships
}
}
]
}

Resource Object

JSON:API documents may contain resource objects to represent objects in the business domain. Unit's resources include applications, customers, cards, accounts, transactions and more.

A resource object MUST contain both the id and the type members.

note

Exception: the id member is not required when the resource object originates at the client and represents a new resource to be created on the server.

In addition, a resource object MAY contain these members:

  • attributes: an attributes object represents some of the resource’s data (examples include the resource name, address, email, etc.)
  • relationships: a relationship object describes the relationship between the current resource and other resources
Resource Example:
{
"type": "individualCustomer",
"id": "53",
"attributes": {
"createdAt": "2020-05-12T19:41:04.123Z",
"fullName": {
"first": "Peter",
"last": "Parker"
},
"nationality": "US",
"ssn": "721074426",
"address": {
"street": "20 Ingram St",
"street2": null,
"city": "Forest Hills",
"state": "NY",
"postalCode": "11375",
"country": "US"
},
"dateOfBirth": "2001-08-15",
"email": "peter@oscorp.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
}
},
"relationships": {
// ... relationships
}
}

Relationships

The relationships object describes the relationship between the current resource and other resources. Each member of the relationships object represents one reference.

In this example, we describe the relationship between a DepositAccount or CreditAccount and the customer it belongs to.

Relationship

A "relationship object" MUST contain a data member with one of the following:

  • null for empty to-one relationships.
  • an empty array ([]) for empty to-many relationships.
  • a single resource identifier (type and id) for non-empty to-one relationships.
  • array of resource identifiers (type and id) for non-empty to-many relationships.
Resource with relationships example:
{
"type": "depositAccount",
"id": "50",
"attributes": {
// ...
},
"relationships": { // relationships object
"customer": { // relationship object
"data": { // resource linkage with single resource identifier
"type": "businessCustomer",
"id": "39"
}
}
}
}

Get operations on certain resources (such as Card) contain an include query parameter that helps you get multiple related resources within the response. You may specify one or more relationships (comma-separated- see example). The response will then contain an included key with the related resources.

The ability to get related resources helps you turn multiple API calls into one. The result is cleaner code and no data integrity questions that usually arise when making multiple API calls at slightly different points in time.

curl -X GET 'https://api.s.unit.sh/cards/41?include=customer,account' \
-H "Authorization: Bearer ${TOKEN}"
Resource with included example:
{
"data": {
"type": "individualDebitCard",
"id": "41",
"attributes": {
"createdAt": "2020-11-30T16:00:52.919Z",
"last4Digits": "0261",
"expirationDate": "2023-11",
"status": "ClosedByCustomer"
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "10156"
}
},
"account": {
"data": {
"type": "account",
"id": "10075"
}
}
}
},
"included": [
{
"type": "depositAccount",
"id": "10075",
"attributes": {
"name": "April Oneil",
"createdAt": "2020-11-30T15:56:59.670Z",
"routingNumber": "812345678",
"accountNumber": "1000000075",
"depositProduct": "checking",
"balance": 144785,
"hold": 0,
"available": 144785,
"tags": {},
"currency": "USD"
},
"relationships": {
"customer": {
"data": {
"type": "customer",
"id": "10156"
}
}
}
},
{
"type": "individualCustomer",
"id": "10156",
"attributes": {
"createdAt": "2020-11-30T15:54:22.788Z",
"fullName": {
"first": "April",
"last": "Oneil"
},
"ssn": "110000002",
"address": {
"street": "20 Ingram St",
"city": "Forest Hills",
"state": "CA",
"postalCode": "11375",
"country": "US"
},
"dateOfBirth": "2001-08-10",
"email": "april@baxter.com",
"phone": {
"countryCode": "1",
"number": "5555555555"
},
"soleProprietorship": false,
"tags": {}
},
"relationships": {
"application": {
"data": {
"type": "application",
"id": "10186"
}
},
"org": {
"data": {
"type": "org",
"id": "1"
}
}
}
}
]
}

Errors

The Unit API uses standard HTTP Status Codes to communicate whether a request has been successfully processed or not. A request may stop processing as soon as a problem is encountered, or it may continue processing and encounter multiple errors. More than one schema validation issues will usually yield multiple errors, while server processing issues will yield a single error. In either case, the response will contain all available errors.

An "error object" MUST contain an HTTP status code member, and may also contain one or more of the following:

  • code: Optional. A Unit-specific underscored code, uniquely identifying the error reported. A growing list of the currently available error codes can be found on the Unit Errors section of the docs.
  • detail: Optional. A human readable description of the error providing additional information about the error.
  • Meta: Optional. A meta object that contains name/value pairs related to the error.
    • meta.supportId Unique error identifier to be used for further investigation.
    • meta.existingIds Optional. Existing IDs of duplicate entries.
Error example:
{
"errors": [
{
"code": "already_exists"
"detail": "Customer is already archived.",
"status": "409",
"meta": {
"supportId": "b4d744af-332a-e7hd-td3c-9bd79a21f35a"
}
}
]
}