Skip to main content

API Conventions

Exact APIs all follow a core set of conventions. These conventions cover things like pagination, HTTP PUT bodies for updates, and response errors, and common status codes.

Query Endpoints​

For query endpoints that list resources, we support using a handful of query string parameters that influence results.

Pagination​

Paginate the list resources using limit and number of results to skip.

  • $skip - Sets the number of results to skip.
  • $limit - Set the number of results to respond with. This is capped at 100 for most endpoints.

Ordering​

Order the list of resources in ascending or descending ordering for any field.

  • $sort - Indicates the sort order. Should be written as a path: $sort[fieldName]=asc. You can sort on multiple fields, and the order in the query string will determine the order in which they are applied: $sort[fieldName1]=asc&$sort[fieldName2]=desc. The value of sort can be either asc or desc.

Filtering​

Filter the list of resources by any field using our many query selectors. It's possible to combine them as needed to retrieve the desired results.

  • $eq - Matches values equal to the specified field value. It can filter identifier, string, numeric, boolean, and date values.

    URLExample
    ?field[$eq]=value?label[$eq]=Payment Token
    ?field=value?createdAt=2021-10-01T22:05:18.262Z
    ?object.field[$eq]=value?merchant.businessProfile.recurringServices[$eq]=true
    ?object.field=value?merchant.entityType=LCC

  • $ne - Matches values different from the specified field value. It can filter out identifier, string, numeric, boolean, and date values.

    URLExample
    ?field[$ne]=value?status[$ne]=approved
    ?object.field[$ne]=value?merchant.address.countrySubdivision[$ne]=AZ

  • $gt - Matches values greater than the specified field value. It can filter string, numeric, and date values.

    URLExample
    ?field[$gt]=value?updatedAt[$gt]=2022-10-01T22:05:18.262Z
    ?object.field[$gt]=value?merchant.businessProfile.acceptanceMethods.internet[$gt]=50

  • $gte - Matches values greater than or equal to the specified field value. It can filter string, numeric, and date values.

    URLExample
    ?field[$gte]=value?liveCapableAt[$gte]=2023-07-21T20:16:52.026Z
    ?object.field[$gte]=value?card.expiry.year[$gte]=2023

  • $lt - Matches values less than the specified field value. It can filter string, numeric, and date values.

    URLExample
    ?field[$lt]=value?disabledAt[$lt]=2023-07-21T20:20:55.750Z
    ?object.field[$lt]=value?settledAt[$lt]='2022-12-31T23:59:59.999Z'

  • $lte - Matches values less than or equal to the specified field value. It can filter string, numeric, and date values.

    URLExample
    ?field[$lte]=value?amount[$lte]=100
    ?object.field[$lte]=value?paymentMethodDetails.expiryYear[$lte]=2022

  • $in - Matches any of the values specified for the array field. It can filter identifier, string, numeric, and date values.

    URLExample
    ?field[$in][0]=value?domain[$in][0]=transaction
    ?field[$in][0]=first&field[$in][1]=second?event[$in][0]=payment.create&event[$in][1]=payment.capture
    ?object.field[$in][0]=value?addresses.state[$in][0]=IL
    ?object.field[$in][0]=first&object.field[$in][1]=second?card.brand[$in][0]=visa&card.brand[$in][1]=amex

  • $nin - Matches none of the values specified in the array field. It can filter out identifier, string, numeric, and date values.

    URLExample
    ?field[$nin][0]=value?type[$nin][0]=application
    ?field[$nin][0]=first&field[$nin][1]=second?status[$nin][0]=approved&status[$nin][1]=declined
    ?object.field[$nin][0]=value?merchant.businessProfile.paymentTime[$nin][0]=Other
    ?object.field[$nin][0]=first&object.field[$nin][1]=second?merchant.principal.address.countrySubdivision[$nin][0]=HI&merchant.principal.address.countrySubdivision[$nin][1]=PA

Response Property Case​

Often programming languages have standards for casing. In order to ease the programming experience when using our API we allow you to change the casing of responses from our system by setting the $propertyCase query string parameter on any request that responds with a body.

  • $propertyCase - Can be set to camelCase, snake_case, or kebab-case. camelCase is the default value.

Common Status Codes​

Our API follows common status code conventions. There are a few status codes you should know as these are used across our API.

General Codes

  • 201 - Returned by POST endpoints when a resource was successfully created.

  • 200 - Returned by GET endpoints when a resource was found and is included in the body of the response.

  • 202 - Returned by POST and PUT endpoints that are asynchronous and a success or failure status cannot be given. The result of these endpoints is usually indicated in a webhook event.

  • 204 - Returned by PUT endpoints when a resource has been modified.

  • 304 - Returned by PUT endpoints when a resource has not been modified because the requested change has already been applied.

  • 401 - Returned by all endpoints that require authentication when either an invalid auth token is used with the request, or a required permission is not assigned to the token or user issuing the request.

  • 403 - Returned by some endpoints when a feature has not been enabled on an account or organization, or the action being performed is not allowed due to configuration.

  • 404 - Returned when an endpoint does not exist, or the path includes an account or organization ID to which the token or user does not have access.

Tokenization Codes

  • 402 - Returned when a customer attempts to tokenize using Network Tokens, but the feature is not enabled

  • 406 - Returned when a $0 auth is not accepted or when network tokenization has failed

  • 428 - Returned when the decryption of encrypted data fails

User Roles and Invites Codes

  • 202 - Returned when a proxy token is created

  • 206 - Returned when there is partial inheritance on roles, partial distribution, partial deletion of roles or the role has been partially enabled or disabled

  • 409 - Returned when the user, or role, already exists

  • 423 - Returned when the user is locked

  • 428 - Returned when the user credentials stored do not contain a password

Documentation Codes

  • 206 - Returned when the uploaded document fails to be uploaded to Dwolla but it was successfully uploaded to Exact

  • 413 - Returned when uploading a document that is too large

  • 415 - Returned when uploading an unsupported document

Reporting Codes

  • 202 - Returned when requesting a new report through the API