Overview

When making calls to the Acquired.com API, a lot of the time, there will be a number of results to return. Our API supports the requirement for multiple objects to be returned in a list. For that reason, we paginate the results to make sure the servers can handle the responses.

We set the default number of objects returned to 25 and the maximum to 100. If you do not specify any query parameters you will receive the most recently created 25.

If the request exceeds the maximum amount, it will either return a 400 - Bad Request response or limit the values returned to 100 regardless of the request exceeding that limit.

Query parameters

The parameters defined by the developer.

Field	Type	Description	Default
`filter`	string	Filter the parameters that you want to return within the response.	N/A
`limit`	integer	A limit on the scope of values returned in the response. This can either be the requested number (with a maximum of 100) or if left blank the first 25 results would be returned.	`25`
`offset`	integer	The record to start the response on.	`0`

📘
Note
When appending the query parameters to your request, you can add them in any order as long as the first parameter is appended with a '?' and subsequent parameters '&'.

Request

{{url}}/customers?filter=customer_id,dob,last_name&limit=30&offset=2

Response

{
  "meta": {
    "count": 30,
    "offset": 2,
    "limit": 30,
    "total": 88
  },
  "data": [
    {
      "customer_id": "5b18a0c0-05de-dfe3-6309-cc703723b0bf",
      "dob": "1994-01-20",
      "last_name": "Barrow"
    },
    {
      "customer_id": "5b18a0c0-05de-dfe3-6309-cc703723b0bf",
      "dob": "1991-09-25",
      "last_name": "Smith"
    }
   ]
}

Metadata responses

This allows you to know how many records and pages there are in total within the response.

Field	Type	Description
`count`	integer	The number of records returned as part of the response.
`offset`	integer	The starting object of the page. This value will be the same value of `offset` in the request.
`limit`	integer	The maximum number of records that can be returned as part of the response.
`total`	integer	The total number of records contained in the query response.

See below example metadata responses:

Assume that there are 77 records as part of the GET /customers examples and look at the responses for metadata.

/customers

{
  "meta": {
    "count": 25,
    "offset": 0,
    "limit": 25,
    "total": 77
  },
  "data": [
    ]
}

/customers?limit=15

{
  "meta": {
    "count": 15,
    "offset": 0,
    "limit": 15,
    "total": 77
  },
  "data": [
    ]
}

/customers?offset=5

{
  "meta": {
    "count": 25,
    "offset": 5,
    "limit": 25,
    "total": 77
  },
  "data": [
    ]
}

/customers?offset=5&limit=5

{
  "meta": {
    "count": 5,
    "offset": 5,
    "limit": 5,
    "total": 77
  },
  "data": [
    ]
}

HATEOAS

We have HATEOAS built into our API responses through the links parameters. HATEOAS specifies that a client should be able to discover the available actions it can perform on a resource dynamically from the resource itself.

When you submit a request into endpoints where a transaction is created, you can then navigate to the links:href parameter and submit a subsequent GET request against the link.

The link is returned in the following endpoints:

/payments
/payments/apple-pay
/payments/google-pay
/payments/recurring
/transactions/{transaction_id}/refund
/transactions/{transaction_id}/void
/transactions/{transaction_id}/capture

Payment response:

{
    "transaction_id": "29c05255-8905-f38f-1446-03f83de52d7c",
    "status": "success",
    "issuer_response_code": "00",
    "check": {
        "avs_line1": "matched",
        "avs_postcode": "matched",
        "cvv": "matched"
    },
    "links": [
        {
            "rel": "self",
            "href": "/v1/transactions/29c05255-8905-f38f-1446-03f83de52d7c"
        }
    ]
}

GET /v1/transactions/29c05255-8905-f38f-1446-03f83de52d7c

Response:

{
    "transaction_id": "29c05255-8905-f38f-1446-03f83de52d7c",
    "status": "success",
    "reason": "",
    "mid": "a36c8fdb-bec8-c121-ac30-9cc41878f3d7",
    "payment_product": "card",
    "payment_method": "authorisation",
    "transaction_type": "payment_in",
    "transaction": {
        "order_id": "3f572650-b90a-4885-a96f-dfdf496720f9",
        "amount": 15.02,
        "currency": "gbp",
        "moto": false,
        "capture": true
    },
    "check": {
        "avs_line1": "matched",
        "avs_postcode": "matched",
        "cvv": "matched"
    },
    "tds": [],
    "issuer_response_code": "00",
    "authorisation_code": "",
    "acquirer_reference_number": "",
    "scheme_reference_data": "",
    "card_id": "",
    "card": {
        "holder_name": "E Johnson",
        "scheme": "visa",
        "number": "2025",
        "expiry_month": 1,
        "expiry_year": 26
    },
    "bin": {
        "issuing_bank": "ACQUIRED.COM",
        "card_category": "DEBIT",
        "product_type": "CONSUMER",
        "card_level": "STANDARD",
        "issuing_country": "United Kingdom",
        "issuing_country_iso2": "GB",
        "eea_indicator": false,
        "non_reloadable": false
    },
    "customer": {
        "reference": "customer_number_00001",
        "first_name": "Edward",
        "last_name": "Johnson",
        "dob": "1988-10-03",
        "ip": "127.0.0.1",
        "billing": {
            "address": {
                "line_1": "152 Aldgate Drive",
                "line_2": "",
                "city": "London",
                "state": "",
                "postcode": "E1 7RT",
                "country_code": "GB"
            },
            "email": "ejohnson@acquired.com",
            "phone": {
                "country_code": "44",
                "number": "2039826580"
            }
        },
        "shipping": {
            "address_match": false,
            "address": {
                "line_1": "152 Aldgate Drive",
                "line_2": "",
                "city": "London",
                "state": "",
                "postcode": "E1 7RT",
                "country_code": "GB"
            },
            "email": "ejohnson@acquired.com",
            "phone": {
                "country_code": "44",
                "number": "2039826580"
            }
        }
    },
    "created": "2023-05-02 14:22:24",
    "last_updated": "2023-05-02 14:22:24",
    "credential_on_file": "null",
    "custom_data": ""
}