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": "15555555"    }  },  "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 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"      }    }  }}

Getting Related Resources#

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#

Unit's API uses HTTP Status Codes to communicate whether a request has been successfully processed. A request may stop processing as soon as a problem is encountered, or it may continue processing and encounter multiple problems. In either case, the response will contain all available errors.

An "error object" MUST contain a title and the HTTP status code members with one or more of the following:

  • code: a Unit-specific code, uniquely identifying the error type.
  • details: additional information about the error.