ExampleRestRequests

Sample Requests

Below are some example Rest Requests using Curl.

1. Requesting a list of deployments
2. Requesting all Invoices for a Deployment
3. Searching for Documents with Pagination
4. Requesting detailed information on a Document
5. Download a document

Requesting a list of deployments

The following example requests a list of deployments for card pools 1234 and 789. It also filters only succesfully deployed deployments.

console

curl -X 'POST' \
  '<API Server>/v1/Deployments' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access Token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "cardPoolIDs": [
    1234,
    789
  ],
  "statusCodes": [
    "Deployed"
  ]
}'

This could return a response similar to below

JSON

{
  "totalItems": 1,
  "totalPages": 0,
  "pageNumber": 0,
  "pageSize": 1,
  "items": [
    {
      "id": 123456,
      "cardpoolID": 789,
      "companyID": 123456,
      "companyName": "Test Company",
      "startDate": "2024-08-08T00:00:00",
      "endDate": "2024-08-08T23:59:59",
      "amount": 1000,
      "currency": "GBP",
      "name": "My Hotel",
      "customerID": null,
      "customerName": null,
      "consumerReference": "7784GT99",
      "created": "2024-08-08T15:07:53.307",
      "amended": "2024-08-08T15:09:05.21"
    }
  ]
}

---

ℹ️ Direct Endpoints Require the the Card Pool ID for the resource. Search endpoints do not.

---

Requesting all Invoices for a Deployment

Considering the above deployment returned with an ID of 123456 we could then request all Invoices for that Deployment.

console

curl -X 'GET' \
  '<API Server>/v1/Deployments/123456/invoices?cardPoolID=789' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access Token>'

This could return a response similar to below

JSON

[
  {
    "id": 4567,
    "deploymentID": 123456,
    "cardPoolID": 789,
    "documentID": 666,
    "supplierInvoiceNo": "ZZZ987",
    "currency": "GBP",
    "vatNumber": "111111111",
    "companyNumber": "666",
    "grossAmount": 134.64,
    "vatAmount": 22.44,
    "netAmount": 112.2,
    "transactionDate": "2024-08-08T08:42:00",
    "createdDate": "2024-08-08T08:44:35.513",
    "lastModifiedDate": null
  }
]

Searching for Documents with Pagination

The following searches for Documents over a date range and requests the second page of results (PageNumber is zero indexed), stating that each page should contain 15 records.

console

curl -X 'POST' \
  '<API Server>/v1/Documents' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer <Access Token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "endDate": "2024-10-23T12:17:36.587Z",
  "startDate": "2024-10-18T12:17:36.587Z",
  "pageNumber": 1,
  "pageSize": 15
}'

This could return a response like below, giving summary information on each document.

JSON

{
  "totalItems": 2,
  "totalPages": 0,
  "pageNumber": 0,
  "pageSize": 2,
  "items": [
    {
      "id": 111,
      "invoiceID": 222,
      "deploymentID": 333,
      "cardPoolID": 444,
      "originalFileName": "M",
      "statusDescription": "Document is linked to the deployment but has not been checked yet",
      "createdDate": "2024-10-22T12:17:36.587Z",
      "amendedDate": null
    },
    {
      "id": 555,
      "invoiceID": 666,
      "deploymentID": 777,
      "cardPoolID": 888,
      "originalFileName": "",
      "statusDescription": "Document has been fully reconciled and rekeyed",
      "createdDate": "2024-10-19T12:17:36.587Z",
      "amendedDate": null
    }
  ]
}

Requesting detailed information on a Document

Whilst the search above will give a summary of each document you may wish to request more information about a specific document.

console

curl -X 'GET' \
  '<API Server>/v1/Documents/555?cardPoolID=888' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer <Access Token>'

Which could return data like this. In this example we can see that this document had a number of correlations which failed.

JSON

{
  "document": {
    "id": 555,
    "invoiceID": 666,
    "deploymentID": 777,
    "cardPoolID": 888,
    "originalFileName": "",
    "statusDescription": "Document has been fully reconciled and rekeyed",
    "createdDate": "2024-10-19T12:17:36.587Z",
    "amendedDate": null
  },
  "documentCorrelations": [
    {
      "code": 1,
      "description": "Check company name appears on the invoice and is correct",
      "name": "Fail"
    },
    {
      "code": 1,
      "description": "Check company address appears on the invoice and is correct",
      "name": "Fail"
    },
    {
      "code": 1,
      "description": "Check company name and address appears on the invoice and is correct",
      "name": "Fail"
    },
    {
      "code": 1,
      "description": "Check company tax number appears on the invoice and is correct",
      "name": "Fail"
    },
    {
      "code": 1,
      "description": "Check supplier name appears on the invoice and is correct",
      "name": "Fail"
    },
    {
      "code": 1,
      "description": "Check supplier address appears on the invoice and is correct",
      "name": "Fail"
    },
    {
      "code": 1,
      "description": "Check supplier name and address appears on the invoice and is correct",
      "name": "Fail"
    }
  ]
}

Download a document

Not only can we gather meta data about a document but we can also download the document itself.

console

curl -X 'GET' \
  '<API Server>/v1/Documents/555/download?cardPoolID=888' \
  -H 'accept: text/plain' \
  -H 'Authorization: Bearer <Access Token>'

This will return a application/octet-stream of the document itself where the filename will be the Document ID.