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.
{
"data": {
"type": "individualCustomer",
"id": "1",
"attributes": {
// ... this customer's attributes
},
"relationships": {
// ... this customer's relationships
}
}
}
{
"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.
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
{
"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:
nullfor empty to-one relationships.- an empty array (
[]) for empty to-many relationships. - a single resource identifier (
typeandid) for non-empty to-one relationships. - array of resource identifiers (
typeandid) for non-empty to-many relationships.
{
"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}"
{
"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.
{
"errors": [
{
"code": "already_exists"
"detail": "Customer is already archived.",
"status": "409",
"meta": {
"supportId": "b4d744af-332a-e7hd-td3c-9bd79a21f35a"
}
}
]
}