API Overview

API Endpoint
https://api.sandbox.relay.ai

Overview

This document describes the Relay API and is designed for anyone who wants to integrate with Relay. More details about relay and how it works for buyers and suppliers can be found here

For any technical assitance please reach out to operations@relay.ai

Connections

Transport

The Relay APIs are RESTful API’s over HTTPS, with JSON being the chosen Content-Type for most of the API’s.

HTTP Headers

In addition to the headers that are required by the verb. For e.g GET requires Accept, POST requires Content-Type, one needs to provide Authorization header too. See also World Wide Web Consortium protocol specification.

The Accept/Content-Type required by Relay API is application/json. Failure to provide these values may result in error code 415 Unsupported Media Type or 406 Not Acceptable

The Authorization header is used for both Authentication and Authorization purposes. This helps us keep a level of protection to make sure the right people are accessing the resources they have access too.

HTTP Methods

Following HTTP Methods are supported by the Relay API, in case you try any other Method you may get back 405 Method Not Allowed

HTTP Status Codes

We follow REST design principles to the very core, hence one should expect to see these status codes in response and handle them gracefully so that there client know what went wrong

Status Code When To Expect
200 Most of the successful GET call will give back this status code along with a response payload.
201 POST call should give back this status code and this would indicate successful creation of a resource.
204 When trying to use DELETE verb, you should expect this on a successful deletion.
400 This status code is a result of validation failure, most likely if the payload contains a value it is not supposed to this can happen.
401 Unsucessful authentication would result in this status code.
403 If a user tries to access a resource he is not permitted too, he will get this error code.
404 If someone tries to GET a resource which does not exist, this is the response code returned back.
5xx Any error code starting is 5, falls under unexpected errors, In case it happens Relay operations is notified immediately and they look into it. Further if this becomes a blocker to you and is urgent, please send an email to operations@relay.ai for quick resolution.

Environments & Endpoints

Relay has two environments that are exposed for Integrations and Relay customers.

  • Sandbox

    • The api endpoint for sandbox is https://api.sandbox.relay.ai
    • When an integrator wants to integrate with Relay, they would get access to Sandbox environment first, Sandbox is a playground and a replica of our production environment, so integrators can use it extensively to try out all the features of relay.
    • Once they have successfully played around and have connected and tested all the features they plan to use, they must get in touch with Relay to get an approval and get setup for production environment.

  • Production

    • The api endpoint for production is https://api.production.relay.ai
    • Once you are done with integration with sandbox and Relay gives an approval, you would be able to access our live production environment.

Versioning

At Relay we are developing APIs all the time, so you should expect the structure may change. However to make it easier for our integrators and to not break their existing integrations, we are going to use a versioning approach with a back support upto last 2 versions only.

Once a new version is planned to be released, you would be notified a week in advance. Even after the release you would be notified about the changes and you should prioritise those changes as per your convenience. When we plan to decomission our oldest version, we would notify you.

For any technical assistance you can always reach out to operations@relay.ai

Security

Authentication

Relay APIs uses Authorization Header to determine th authenticity of the user using the APIs. We have three actors who can use Relay APIs

  • Buyers/Suppliers

    • These are the direct customers of Relay who belongs to a company.
    • They usually go through a signup and identity verification process and upon success they get credentials which they then use, to use our platform.
    • In the background for a given successul username/password, Relay generates a JWS token and that token expires in an hour. This token is used as part of the Authorization header and every API would first validate this token before actioning any resource

  • Integrator

    • These are third parties who wants to give their customers access to Relay through their platforms
    • While we are working towards creating an OAuth2 Server and a self onboarding portal, as of now to get access, they need to get in touch with operations@relay.ai and go through a manual onboarding and verification process.
    • Upon success they would be given an API key which they would be using as part of their Authorization header to call any futher Relay APIs
    • Throttling limits are going to be put in place and the Operations team would be monitoring the usage of how these integrators are using the APIs.
    • It is advised to make sure the code written is efficient and doesnt make any unnecessary calls to the Relay APIs and caching is used as and when possible.

  • Admins

    • Admins are super user who have access to all the features of Relay.
    • Only specific company employee has an admin privilege and they only use Relay for operational and support purposes

Bearer Token

Generate a bearer token based on client-id and client-secret

Create Bearer Token

POST https://api.sandbox.relay.ai/bearer
Requestswith body
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Basic (Base64 encoded clientid:clientsecret)
Body
grant_type: client_credentials
Responses200
Headers
Content-Type: application/json
Content-Type: application/json
Body
{
  "issued_at": "1589852137",
  "application_name": "client-app-name",
  "scope": "",
  "status": "approved",
  "expires_in": "3599",
  "token_type": "BearerToken",
  "client_id": "axxxxxxxxxxx",
  "access_token": "bxxxxxxx"
}

Create Bearer Token
POST/bearer

Generate a bearer token based on client-id and client-secret

Not yet supported

Hateoas & Pagination

Below are the list of APIs that are used to do some action on the invoices or bills object

Hateoas

HATEOAS (Hypertext As The Engine Of Application State) links are included as part of the JSON response body, to help guide the client on how to use the API. More details can be found here

These are the type of links one can expect to be returned as part of response payload:

  • self link: link of the current resource

  • related resource instance links: link of the resources who are related to the resoruce

  • next / prev links: next and previous links in paginated resources. Links to help client navigate through pages, if the response returned is paginated.

Pagination

Searching on various resources (GET with query params) will result in response being returned in page form. There are 2 query params which control the flow of pages

page: Indicating the current page you are on, the first page is always 0 and this is the default value in case you haven’t provided anything

size: the number of items returned per page. The default value is 5.

The HATEOAS next and prev links are used to navigate between the pages of search results

User

Below are the list of APIs that are used to do some action on the user object

Create New User

POST https://api.sandbox.relay.ai/user/signup
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "username": "sind@relay.ai"
}
Responses201
Headers
Content-Type: application/json

Create New User
POST/user/signup

Create a new user in Relay

Field Required Description
username Y username of the user

Get User

GET https://api.sandbox.relay.ai/user
Requestswithout body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
{
  "user": {
    "id": "2d7d8954-014b-4f86-8eb0-a6ff3738f7e8",
    "firstName": null,
    "middleName": null,
    "lastName": null,
    "username": "sind@relay.ai",
    "password": "$2a$10$sqa4xcV.fZwwhBN7LIWoceiXQVcipVNCoAWSKXTgHvw2LLHiy6NDy",
    "phoneNumber": null,
    "companyId": "110773bd-4633-4c4d-b6c8-b4743b0f0828",
    "status": "UNVERIFIED",
    "roles": [
      "ROLE_USER"
    ],
    "address": null,
    "dateOfBirth": null,
    "verifyWith": null,
    "verificationStatus": "NOT_VERIFIED",
    "phoneNumberVerified": false,
    "addressVerified": false,
    "driversLicenceNumber": null,
    "driversLicenceVersion": null,
    "verificationDocLink": null,
    "passportNumber": null,
    "passportExpiry": null,
    "creationTime": 1589934081220,
    "modificationTime": 1589934081436,
    "lastModifiedBy": "sind@relay.ai"
  },
  "_links": {
    "self": {
      "href": "https://api.dev.relay.ai/user"
    }
  }
}

Get User
GET/user

Update User

PUT https://api.sandbox.relay.ai/user/e05ad5ea
Requestswith body
Headers
Accept: application/json
Authorization: Bearer "access_token"
Body
{
  "id": "2d7d8954-014b-4f86-8eb0-a6ff3738f7e8",
  "firstName": "Siddarth",
  "middleName": "",
  "lastName": "Sharma",
  "username": "sind@relay.ai",
  "password": "P@ssword12345",
  "phoneNumber": null,
  "companyId": "110773bd-4633-4c4d-b6c8-b4743b0f0828",
  "status": "UNVERIFIED",
  "roles": [
    "ROLE_USER"
  ],
  "address": null,
  "dateOfBirth": null,
  "verifyWith": null,
  "verificationStatus": "NOT_VERIFIED",
  "phoneNumberVerified": false,
  "addressVerified": false,
  "driversLicenceNumber": null,
  "driversLicenceVersion": null,
  "verificationDocLink": null,
  "passportNumber": null,
  "passportExpiry": null,
  "creationTime": 1589934081220,
  "modificationTime": 1589934081436,
  "lastModifiedBy": "sind@relay.ai"
}
Responses200
Headers
Content-Type: application/json
Body
{
  "user": {
    "id": "2d7d8954-014b-4f86-8eb0-a6ff3738f7e8",
    "firstName": "Siddarth",
    "middleName": "",
    "lastName": "Sharma",
    "username": "sind@relay.ai",
    "password": "$2a$10$v87.IjO3O9yGlSK.dly4JOO8QgmOjACLWZnNuFc.28QbXgtcNqHtW",
    "phoneNumber": null,
    "companyId": "110773bd-4633-4c4d-b6c8-b4743b0f0828",
    "status": "ACTIVE",
    "roles": [
      "ROLE_USER"
    ],
    "address": null,
    "dateOfBirth": null,
    "verifyWith": null,
    "verificationStatus": "NOT_VERIFIED",
    "phoneNumberVerified": false,
    "addressVerified": false,
    "driversLicenceNumber": null,
    "driversLicenceVersion": null,
    "verificationDocLink": null,
    "passportNumber": null,
    "passportExpiry": null,
    "creationTime": 1589934081220,
    "modificationTime": 1589934327065,
    "lastModifiedBy": "sind@relay.ai"
  },
  "_links": {
    "self": {
      "href": "https://api.dev.relay.ai/user"
    }
  }
}

Update User
PUT/user/{id}

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the user

Company

Below are the list of APIs that are used to do some action on the company object

Create New Company

POST https://api.sandbox.relay.ai/company
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "nzbn": "9429033681122",
  "companyName": "ARD LIMITED",
  "registrationNumber": "1897230",
  "industryCode": ""
}
Responses201
Headers
Content-Type: application/json
Body
{
  "company": {
    "id": "0e342854-ef77-4674-a4af-38233bbdeba2",
    "companyName": "Ard Limited",
    "registrationNumber": "1897230",
    "industryCode": "",
    "acknowledgementTimestamp": null,
    "acknowledgementText": null,
    "nzbn": "9429033681122",
    "gstNumber": null,
    "website": null,
    "fundsAvailable": 0,
    "address": null,
    "status": "ACTIVE",
    "onboardedBy": "RELAY",
    "connectedToXero": false,
    "connectedToMyobEssentials": false,
    "connectedToMyobAccountRight": false,
    "xeroAccountsConfigured": false,
    "myobEssentialsAccountsConfigured": false,
    "myobAccountRightAccountsConfigured": false,
    "aliases": null,
    "verified": null,
    "invitedBy": null,
    "creationTime": 1589860816129,
    "modificationTime": 1589860816129
  },
  "_links": {
    "self": {
      "href": "https://api.dev.relay.ai/company/0e342854-ef77-4674-a4af-38233bbdeba2"
    }
  }
}

Create New Company
POST/company

Create a new company in Relay

Field Required Description
nzbn Y registered NZ business number of the company
companyName Y legal company name as mentioned in the Company Register
registrationNumber N gstNumber of the company
industryCode N industry classification code of the company

Update Company

PUT https://api.sandbox.relay.ai/company/e05ad5ea
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "id": "0e342854-ef77-4674-a4af-38233bbdeba2",
  "companyName": "Ard Limited",
  "registrationNumber": "1897230",
  "industryCode": "",
  "acknowledgementTimestamp": 1589867597435,
  "acknowledgementText": "By clicking confirm, you warrant that you are an authorised representative of Ard Limited and have authorisation to make payments on behalf of Ard Limited.",
  "nzbn": "9429033681122",
  "gstNumber": null,
  "website": "www.relay.ai",
  "fundsAvailable": 0,
  "address": null,
  "status": "ACTIVE",
  "onboardedBy": "RELAY",
  "connectedToXero": false,
  "connectedToMyobEssentials": false,
  "connectedToMyobAccountRight": false,
  "xeroAccountsConfigured": false,
  "myobEssentialsAccountsConfigured": false,
  "myobAccountRightAccountsConfigured": false,
  "aliases": null,
  "verified": null,
  "invitedBy": null,
  "creationTime": 1589860816129,
  "modificationTime": 1589860816129
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "0e342854-ef77-4674-a4af-38233bbdeba2",
  "companyName": "Ard Limited",
  "registrationNumber": "1897230",
  "industryCode": "",
  "acknowledgementTimestamp": 1589867597435,
  "acknowledgementText": "By clicking confirm, you warrant that you are an authorised representative of Ard Limited and have authorisation to make payments on behalf of Ard Limited.",
  "nzbn": "9429033681122",
  "gstNumber": null,
  "website": "www.relay.ai",
  "fundsAvailable": 0,
  "address": null,
  "status": "ACTIVE",
  "onboardedBy": "RELAY",
  "connectedToXero": false,
  "connectedToMyobEssentials": false,
  "connectedToMyobAccountRight": false,
  "xeroAccountsConfigured": false,
  "myobEssentialsAccountsConfigured": false,
  "myobAccountRightAccountsConfigured": false,
  "aliases": null,
  "verified": null,
  "invitedBy": null,
  "creationTime": 1589860816129,
  "modificationTime": 1589860816129
}

Update Company
PUT/company/{id}

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the company

GET Company

GET https://api.sandbox.relay.ai/company/e05ad5ea
Requestswithout body
Headers
Accept: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
{
  "company": {
    "id": "0e342854-ef77-4674-a4af-38233bbdeba2",
    "companyName": "Ard Limited",
    "registrationNumber": "1897230",
    "industryCode": "",
    "acknowledgementTimestamp": 1589867597435,
    "acknowledgementText": "By clicking confirm, you warrant that you are an authorised representative of Ard Limited and have authorisation to make payments on behalf of Ard Limited.",
    "nzbn": "9429033681122",
    "gstNumber": null,
    "website": "www.relay.ai",
    "fundsAvailable": 0,
    "address": null,
    "status": "ACTIVE",
    "onboardedBy": "RELAY",
    "connectedToXero": false,
    "connectedToMyobEssentials": false,
    "connectedToMyobAccountRight": false,
    "xeroAccountsConfigured": false,
    "myobEssentialsAccountsConfigured": false,
    "myobAccountRightAccountsConfigured": false,
    "aliases": null,
    "verified": null,
    "invitedBy": null,
    "creationTime": 1589860816129,
    "modificationTime": 1589867597727
  },
  "_links": {
    "self": {
      "href": "https://api.dev.relay.ai/company/0e342854-ef77-4674-a4af-38233bbdeba2"
    }
  }
}

GET Company
GET/company/{id}

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the company

BankAccount

Below are the list of APIs that are used to do some action on the withdrawal object

Create New BankAccount

POST https://api.sandbox.relay.ai/company/e05ad5ea/bankaccount
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "bankAccountName": "ANZ",
  "bankAccountNumber": "1111111111111111",
  "defaultAccount": true
}
Responses201
Headers
Content-Type: application/json
Body
{
  "id": "bcdc068b-1244-43b9-9700-fad430c56ca6",
  "bankAccountName": "ANZ",
  "bankAccountNumber": "1111111111111111",
  "bankAccountStatus": "UNVERIFIED",
  "loadedBy": "RELAY",
  "defaultAccount": true,
  "linkToStatement": null,
  "creationTime": 1589937193850,
  "modificationTime": 1589937193850
}

Create New BankAccount
POST/company/{id}/bankaccount

Add a new bankaccount

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the company

Get BankAccount

GET https://api.sandbox.relay.ai/company/e05ad5ea/bankaccounts
Requestswithout body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "id": "bcdc068b-1244-43b9-9700-fad430c56ca6",
    "bankAccountName": "ANZ",
    "bankAccountNumber": "1111111111111111",
    "bankAccountStatus": "UNVERIFIED",
    "loadedBy": "RELAY",
    "defaultAccount": true,
    "linkToStatement": null,
    "creationTime": 1589937193850,
    "modificationTime": 1589937193850
  },
  {
    "id": "fbc6a096-3893-42b5-8ae2-459ebd9c0d5b",
    "bankAccountName": "Relay",
    "bankAccountNumber": "1111111111111007",
    "bankAccountStatus": "UNVERIFIED",
    "loadedBy": "SYSTEM",
    "defaultAccount": false,
    "linkToStatement": null,
    "creationTime": 1589517979719,
    "modificationTime": 1589517979719
  }
]

Get BankAccount
GET/company/{id}/bankaccounts

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the company

Verify Bank Account

POST https://api.sandbox.relay.ai/company/e05ad5ea/bankaccount/e05ad5ea/verify
Requestswith body
Headers
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer "access_token"
Body
file: file
Responses201
Headers
Content-Type: application/x-www-form-urlencoded
Body
File successfully submitted for verification

Verify Bank Account
POST/company/{id}/bankaccount/{bankaccountId}/verify

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the company

bankaccountId
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the bankaccount

Topup

Below are the list of APIs that are used to do some action on the topup object

Create New Topup

POST https://api.sandbox.relay.ai/company/e05ad5ea/topup
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "topupAmount": 1000
}
Responses201
Headers
Content-Type: application/json
Body
{
  "topup": {
    "id": "2453119e-5150-4c6d-8eec-7ee713f5314c",
    "topupAmount": 1000,
    "topupStatus": "PENDING",
    "assignedBankAccount": "1111111111111007",
    "creationTime": 1589934655758,
    "modificationTime": 1589934655758
  },
  "_links": {
    "self": {
      "href": "http://localhost:8080/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56/topup/2453119e-5150-4c6d-8eec-7ee713f5314c"
    },
    "company": {
      "href": "http://localhost:8080/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
    }
  }
}

Create New Topup
POST/company/{id}/topup

Create a new topup

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the company

Get topups

GET https://api.sandbox.relay.ai/company/e05ad5ea/topup
Requestswithout body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
{
  "pageNumber": 0,
  "pageSize": 20,
  "totalPages": 1,
  "totalElements": 3,
  "topups": [
    {
      "topup": {
        "id": "8502e7a7-7de5-494d-9b49-65211cf8aa01",
        "topupAmount": 1000,
        "topupStatus": "COMPLETED",
        "assignedBankAccount": "1111111111111007",
        "creationTime": 1589864327880,
        "modificationTime": 1589931167301
      },
      "_links": {
        "self": {
          "href": "http://localhost:8080/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56/topup/8502e7a7-7de5-494d-9b49-65211cf8aa01"
        },
        "company": {
          "href": "http://localhost:8080/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
        }
      }
    },
    {
      "topup": {
        "id": "7f9f544e-cc7d-419f-933b-1488f6409d00",
        "topupAmount": 1000,
        "topupStatus": "COMPLETED",
        "assignedBankAccount": "1111111111111007",
        "creationTime": 1589930055387,
        "modificationTime": 1589931168165
      },
      "_links": {
        "self": {
          "href": "http://localhost:8080/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56/topup/7f9f544e-cc7d-419f-933b-1488f6409d00"
        },
        "company": {
          "href": "http://localhost:8080/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
        }
      }
    },
    {
      "topup": {
        "id": "2453119e-5150-4c6d-8eec-7ee713f5314c",
        "topupAmount": 1000,
        "topupStatus": "PENDING",
        "assignedBankAccount": "1111111111111007",
        "creationTime": 1589934655758,
        "modificationTime": 1589934655758
      },
      "_links": {
        "self": {
          "href": "http://localhost:8080/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56/topup/2453119e-5150-4c6d-8eec-7ee713f5314c"
        },
        "company": {
          "href": "http://localhost:8080/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
        }
      }
    }
  ]
}

Get topups
GET/company/{id}/topup

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the company

Get Particular Topup

GET https://api.sandbox.relay.ai/company/e05ad5ea/topup/e05ad5ea
Requestswithout body
Headers
Accept: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
{
  "topup": {
    "id": "8502e7a7-7de5-494d-9b49-65211cf8aa01",
    "topupAmount": 1000,
    "topupStatus": "COMPLETED",
    "assignedBankAccount": "1111111111111007",
    "creationTime": 1589864327880,
    "modificationTime": 1589931167301
  },
  "_links": {
    "self": {
      "href": "http://localhost:8080/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56/topup/8502e7a7-7de5-494d-9b49-65211cf8aa01"
    },
    "company": {
      "href": "http://localhost:8080/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
    }
  }
}

Get Particular Topup
GET/company/{id}/topup/{topupId}

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the company

topupId
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the topup

Withdrawal

Below are the list of APIs that are used to do some action on the withdrawal object

Create New Withdrawal

POST https://api.sandbox.relay.ai/company/e05ad5ea/withdrawal
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "bankAccountId": "bcdc068b-1244-43b9-9700-fad430c56ca6",
  "withdrawalAmount": "200.00"
}
Responses201
Headers
Content-Type: application/json
Body
{
  "withdrawal": {
    "id": "cac81275-3610-4a15-81e2-70c693586a4d",
    "bankAccountId": "bcdc068b-1244-43b9-9700-fad430c56ca6",
    "withdrawalAmount": 200,
    "withdrawalStatus": "COMPLETED",
    "creationTime": null,
    "modificationTime": null
  },
  "_links": {
    "self": {
      "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56/withdrawal/cac81275-3610-4a15-81e2-70c693586a4d"
    },
    "company": {
      "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
    }
  }
}

Create New Withdrawal
POST/company/{id}/withdrawal

Create a new withdrawal

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the company

Transaction

Below are the list of APIs that are used to do some action on the transaction object

Get Transactions

GET https://api.sandbox.relay.ai/transaction
Requestswithout body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
{
  "pageNumber": 0,
  "pageSize": 20,
  "totalPages": 1,
  "totalElements": 5,
  "transactions": [
    {
      "transaction": {
        "id": "d79154ba-fad5-4ce1-9a8f-3eb075b5c117",
        "sourceCompanyName": "",
        "sourceCompanyId": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "sourceBankAccount": "",
        "sourceParticulars": "Relay topup",
        "sourceCode": "",
        "sourceReference": "TOP515LPH",
        "sourceAccountBalance": 2900.19,
        "sourceBank": null,
        "transactionAmount": 1000,
        "destinationCompanyName": "Gla Trustee Holdings Limited",
        "destinationCompanyId": null,
        "destinationBankAccount": null,
        "destinationParticulars": null,
        "destinationCode": null,
        "destinationReference": null,
        "destinationAccountBalance": null,
        "destinationBank": null,
        "status": "PENDING",
        "transactionClass": "TOPUP",
        "reconciled": false,
        "creationTime": 1589934656278,
        "modificationTime": 1589934656627,
        "createdBy": "gla@zinc.nz",
        "lastModifiedBy": "gla@zinc.nz"
      },
      "_links": {
        "self": {
          "href": "http://localhost:8080/transaction/d79154ba-fad5-4ce1-9a8f-3eb075b5c117"
        }
      }
    },
    {
      "transaction": {
        "id": "8eaef7d6-b765-42a6-97af-a2a6ff499eb8",
        "sourceCompanyName": "Relay Limited",
        "sourceCompanyId": null,
        "sourceBankAccount": null,
        "sourceParticulars": null,
        "sourceCode": null,
        "sourceReference": null,
        "sourceAccountBalance": null,
        "sourceBank": null,
        "transactionAmount": 0.19,
        "destinationCompanyName": "Gla Trustee Holdings Limited",
        "destinationCompanyId": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "destinationBankAccount": "1111111111111007",
        "destinationParticulars": "CashReward",
        "destinationCode": "",
        "destinationReference": "R42BJL",
        "destinationAccountBalance": 1900.19,
        "destinationBank": null,
        "status": "COMPLETED",
        "transactionClass": "PAYMENT",
        "reconciled": false,
        "creationTime": 1589932298835,
        "modificationTime": 1589932299012,
        "createdBy": "aero@relay.ai",
        "lastModifiedBy": "aero@relay.ai"
      },
      "_links": {
        "self": {
          "href": "http://localhost:8080/transaction/8eaef7d6-b765-42a6-97af-a2a6ff499eb8"
        }
      }
    },
    {
      "transaction": {
        "id": "0ca0042a-ebd2-4bd3-a5a3-c8c6c8942726",
        "sourceCompanyName": "Gla Trustee Holdings Limited",
        "sourceCompanyId": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "sourceBankAccount": "1111111111111007",
        "sourceParticulars": "EarlyPayment",
        "sourceCode": "",
        "sourceReference": "P42BJL",
        "sourceAccountBalance": 1900,
        "sourceBank": null,
        "transactionAmount": 100,
        "destinationCompanyName": "Aer Group Limited",
        "destinationCompanyId": null,
        "destinationBankAccount": null,
        "destinationParticulars": null,
        "destinationCode": null,
        "destinationReference": null,
        "destinationAccountBalance": null,
        "destinationBank": null,
        "status": "COMPLETED",
        "transactionClass": "PAYMENT",
        "reconciled": false,
        "creationTime": 1589932295008,
        "modificationTime": 1589932295253,
        "createdBy": "aero@relay.ai",
        "lastModifiedBy": "aero@relay.ai"
      },
      "_links": {
        "self": {
          "href": "http://localhost:8080/transaction/0ca0042a-ebd2-4bd3-a5a3-c8c6c8942726"
        }
      }
    },
    {
      "transaction": {
        "id": "2cd71971-e9af-428d-89b6-d5b3e8a4adb8",
        "sourceCompanyName": "",
        "sourceCompanyId": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "sourceBankAccount": "",
        "sourceParticulars": "Relay topup",
        "sourceCode": "",
        "sourceReference": "TOP598EAU",
        "sourceAccountBalance": 2000,
        "sourceBank": null,
        "transactionAmount": 1000,
        "destinationCompanyName": "Gla Trustee Holdings Limited",
        "destinationCompanyId": null,
        "destinationBankAccount": null,
        "destinationParticulars": null,
        "destinationCode": null,
        "destinationReference": null,
        "destinationAccountBalance": null,
        "destinationBank": null,
        "status": "COMPLETED",
        "transactionClass": "TOPUP",
        "reconciled": true,
        "creationTime": 1589931168094,
        "modificationTime": 1589931168095,
        "createdBy": "gla@zinc.nz",
        "lastModifiedBy": "utsav@relay.ai"
      },
      "_links": {
        "self": {
          "href": "http://localhost:8080/transaction/2cd71971-e9af-428d-89b6-d5b3e8a4adb8"
        }
      }
    },
    {
      "transaction": {
        "id": "c0d22c43-2eae-4dbd-99f4-00d8f97345bf",
        "sourceCompanyName": "",
        "sourceCompanyId": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "sourceBankAccount": "",
        "sourceParticulars": "Relay topup",
        "sourceCode": "",
        "sourceReference": "TOP246EBA",
        "sourceAccountBalance": 1000,
        "sourceBank": null,
        "transactionAmount": 1000,
        "destinationCompanyName": "Gla Trustee Holdings Limited",
        "destinationCompanyId": null,
        "destinationBankAccount": null,
        "destinationParticulars": null,
        "destinationCode": null,
        "destinationReference": null,
        "destinationAccountBalance": null,
        "destinationBank": null,
        "status": "COMPLETED",
        "transactionClass": "TOPUP",
        "reconciled": true,
        "creationTime": 1589931167206,
        "modificationTime": 1589931167214,
        "createdBy": "gla@zinc.nz",
        "lastModifiedBy": "utsav@relay.ai"
      },
      "_links": {
        "self": {
          "href": "http://localhost:8080/transaction/c0d22c43-2eae-4dbd-99f4-00d8f97345bf"
        }
      }
    }
  ]
}

Get Transactions
GET/transaction

Get Particular Transaction

GET https://api.sandbox.relay.ai/transaction/e05ad5ea
Requestswithout body
Headers
Accept: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
{
  "transaction": {
    "id": "d79154ba-fad5-4ce1-9a8f-3eb075b5c117",
    "sourceCompanyName": "",
    "sourceCompanyId": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
    "sourceBankAccount": "",
    "sourceParticulars": "Relay topup",
    "sourceCode": "",
    "sourceReference": "TOP515LPH",
    "sourceAccountBalance": 2900.19,
    "sourceBank": null,
    "transactionAmount": 1000,
    "destinationCompanyName": "Gla Trustee Holdings Limited",
    "destinationCompanyId": null,
    "destinationBankAccount": null,
    "destinationParticulars": null,
    "destinationCode": null,
    "destinationReference": null,
    "destinationAccountBalance": null,
    "destinationBank": null,
    "status": "PENDING",
    "transactionClass": "TOPUP",
    "reconciled": false,
    "creationTime": 1589934656278,
    "modificationTime": 1589934656627,
    "createdBy": "gla@zinc.nz",
    "lastModifiedBy": "gla@zinc.nz"
  },
  "_links": {
    "self": {
      "href": "http://localhost:8080/transaction/d79154ba-fad5-4ce1-9a8f-3eb075b5c117"
    }
  }
}

Get Particular Transaction
GET/transaction/{id}

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the transaction

Invoices

Below are the list of APIs that are used to do some action on the invoices or bills object

Create New Invoice

POST https://api.sandbox.relay.ai/invoice
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "dueDate": 1590580800000,
  "total": "100.00",
  "issuedBy": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
  "issuedForCompanyName": "WIND CO LIMITED",
  "invoiceNumber": "1011"
}
Responses201
Headers
Content-Type: application/json
Body
{
  "invoice": {
    "id": "ddd4cd2b-4019-4674-b44d-3545ddbda7ac",
    "invoiceNumber": "1011",
    "billNumber": null,
    "issuedBy": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
    "addedAs": "INVOICE",
    "issuedByCompanyName": "Gla Trustee Holdings Limited",
    "issuedFor": "a2c7636a-d694-40c3-8b3c-eab2abdcdba5",
    "issuedForCompanyName": "Wind Co Limited",
    "jobReference": null,
    "transactionReference": null,
    "invoiceLoadedBy": "RELAY",
    "billLoadedBy": null,
    "approvalRequired": false,
    "includeInPurchaserOffer": false,
    "matched": false,
    "dueDate": 1590580800000,
    "invoiceStatus": "NO_CASHBACK",
    "billStatus": "NO_CASHBACK",
    "items": null,
    "subTotal": null,
    "gst": null,
    "total": 100,
    "totalPaid": null,
    "relayFee": null,
    "pendingAmount": null,
    "paidDate": null,
    "creationTime": 1589853221052,
    "modificationTime": 1589853221052,
    "owingCompany": {
      "id": "a2c7636a-d694-40c3-8b3c-eab2abdcdba5",
      "companyName": "Wind Co Limited",
      "registrationNumber": null,
      "industryCode": null,
      "acknowledgementTimestamp": null,
      "acknowledgementText": null,
      "nzbn": null,
      "gstNumber": null,
      "website": null,
      "fundsAvailable": 0,
      "address": null,
      "status": "INACTIVE",
      "onboardedBy": "RELAY",
      "connectedToXero": false,
      "connectedToMyobEssentials": false,
      "connectedToMyobAccountRight": false,
      "xeroAccountsConfigured": false,
      "myobEssentialsAccountsConfigured": false,
      "myobAccountRightAccountsConfigured": false,
      "aliases": [
        {
          "forCompany": "Gla Trustee Holdings Limited",
          "alias": "Wind Co Limited"
        }
      ],
      "verified": null,
      "invitedBy": null,
      "creationTime": 1589853220676,
      "modificationTime": 1589853220676
    },
    "companyOwed": {
      "id": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
      "companyName": "Gla Trustee Holdings Limited",
      "registrationNumber": "4122058",
      "industryCode": "K641965",
      "acknowledgementTimestamp": 1589768380761,
      "acknowledgementText": "By clicking confirm, you warrant that you are an authorised representative of Gla Trustee Holdings Limited and have authorisation to make payments on behalf of Gla Trustee Holdings Limited.",
      "nzbn": "9429030434806",
      "gstNumber": null,
      "website": null,
      "fundsAvailable": 0,
      "address": null,
      "status": "ACTIVE",
      "onboardedBy": "RELAY",
      "connectedToXero": false,
      "connectedToMyobEssentials": false,
      "connectedToMyobAccountRight": false,
      "xeroAccountsConfigured": false,
      "myobEssentialsAccountsConfigured": false,
      "myobAccountRightAccountsConfigured": false,
      "aliases": null,
      "verified": true,
      "invitedBy": null,
      "creationTime": 1589517979583,
      "modificationTime": 1589768380977
    }
  },
  "_links": {
    "self": {
      "href": "https://api.dev.relay.ai/invoice/ddd4cd2b-4019-4674-b44d-3545ddbda7ac"
    },
    "companyOwed": {
      "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
    },
    "owingCompany": {
      "href": "https://api.dev.relay.ai/company/a2c7636a-d694-40c3-8b3c-eab2abdcdba5"
    }
  }
}

Create New Invoice
POST/invoice

Create a new invoice

Field Required Description
dueDate Y Date when the invoice is due. In epoch time format
total Y total amount due
issuedBy Y relay UUID of the company who is creating invoice
issuedForCompanyName Y buyer/purchaser company name
invoiceNumber Y a user friendly number for identification of invoice

Create New Bill

POST https://api.sandbox.relay.ai/invoice
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "dueDate": 1590494400000,
  "total": "100.00",
  "issuedFor": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
  "issuedByCompanyName": "AER GROUP LIMITED",
  "billNumber": "1012"
}
Responses201
Headers
Content-Type: application/json
Body
{
  "invoice": {
    "id": "0c2b9004-d4f0-459f-bef6-ef0320a3a352",
    "invoiceNumber": null,
    "billNumber": "1012",
    "issuedBy": "231905ef-5c5d-4426-a448-c703730e0859",
    "addedAs": "BILL",
    "issuedByCompanyName": "Aer Group Limited",
    "issuedFor": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
    "issuedForCompanyName": "Gla Trustee Holdings Limited",
    "jobReference": null,
    "transactionReference": null,
    "invoiceLoadedBy": null,
    "billLoadedBy": "RELAY",
    "approvalRequired": false,
    "includeInPurchaserOffer": false,
    "matched": false,
    "dueDate": 1590494400000,
    "invoiceStatus": "NO_CASHBACK",
    "billStatus": "NO_CASHBACK",
    "items": null,
    "subTotal": null,
    "gst": null,
    "total": 100,
    "totalPaid": null,
    "relayFee": null,
    "pendingAmount": null,
    "paidDate": null,
    "creationTime": 1589854259636,
    "modificationTime": 1589854259636,
    "owingCompany": {
      "id": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
      "companyName": "Gla Trustee Holdings Limited",
      "registrationNumber": "4122058",
      "industryCode": "K641965",
      "acknowledgementTimestamp": 1589768380761,
      "acknowledgementText": "By clicking confirm, you warrant that you are an authorised representative of Gla Trustee Holdings Limited and have authorisation to make payments on behalf of Gla Trustee Holdings Limited.",
      "nzbn": "9429030434806",
      "gstNumber": null,
      "website": null,
      "fundsAvailable": 0,
      "address": null,
      "status": "ACTIVE",
      "onboardedBy": "RELAY",
      "connectedToXero": false,
      "connectedToMyobEssentials": false,
      "connectedToMyobAccountRight": false,
      "xeroAccountsConfigured": false,
      "myobEssentialsAccountsConfigured": false,
      "myobAccountRightAccountsConfigured": false,
      "aliases": null,
      "verified": true,
      "invitedBy": null,
      "creationTime": 1589517979583,
      "modificationTime": 1589768380977
    },
    "companyOwed": {
      "id": "231905ef-5c5d-4426-a448-c703730e0859",
      "companyName": "Aer Group Limited",
      "registrationNumber": null,
      "industryCode": null,
      "acknowledgementTimestamp": null,
      "acknowledgementText": null,
      "nzbn": null,
      "gstNumber": null,
      "website": null,
      "fundsAvailable": 0,
      "address": null,
      "status": "INACTIVE",
      "onboardedBy": "RELAY",
      "connectedToXero": false,
      "connectedToMyobEssentials": false,
      "connectedToMyobAccountRight": false,
      "xeroAccountsConfigured": false,
      "myobEssentialsAccountsConfigured": false,
      "myobAccountRightAccountsConfigured": false,
      "aliases": [
        {
          "forCompany": "Gla Trustee Holdings Limited",
          "alias": "Aer Group Limited"
        }
      ],
      "verified": null,
      "invitedBy": null,
      "creationTime": 1589854259502,
      "modificationTime": 1589854259502
    }
  },
  "_links": {
    "self": {
      "href": "https://api.dev.relay.ai/invoice/0c2b9004-d4f0-459f-bef6-ef0320a3a352"
    },
    "companyOwed": {
      "href": "https://api.dev.relay.ai/company/231905ef-5c5d-4426-a448-c703730e0859"
    },
    "owingCompany": {
      "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
    }
  }
}

Create New Bill
POST/invoice

Create a new bill

Field Required Description
dueDate Y Date when the invoice is due. In epoch time format
total Y total amount due
issuedFor Y relay UUID of the company who is creating the bill
issuedByCompanyName Y supplier company name
billNumber Y a user friendly number for identification of invoice

Import Invoices

POST https://api.sandbox.relay.ai/invoice/import
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "type": "BILL",
  "invoices": [
    {
      "issuedFor": "3f6bbb2c-226e-4590-b741-80c59eda629a",
      "issuedByCompanyName": "Sup Limited",
      "dueDate": 1577876400000,
      "total": "315.10",
      "billNumber": "BILL00111"
    },
    {
      "issuedFor": "8246daa7-c5fe-4b39-bd25-e91444e0b0ec",
      "issuedByCompanyName": "Sup Limited",
      "dueDate": 1577876400000,
      "total": "460",
      "billNumber": "BILL002"
    }
  ]
}
Responses201
Headers
Content-Type: application/json
Body
{
  "total": 2,
  "success": 2,
  "failed": 0
}

Import Invoices
POST/invoice/import

Rather than manually creating invoices or bill, you can also bulk import invoices or bill.

The fields needed are exactly the same as that for creating an invoice for bulk importing invoices.

They are exactly the same for importing and creating bills as well.

Although there is one extra field that is added to the outer JSON payload indicating whether we are bulk importing invoices or bill. Look at the structure mentioned here to understand how it works

Get Invoices

GET https://api.sandbox.relay.ai/invoice
Responses200
Headers
Accept: application/json
Authorization: Bearer "access_token"
Body
{
  "pageNumber": 0,
  "pageSize": 5,
  "totalPages": 5,
  "totalElements": 25,
  "invoices": [
    {
      "invoice": {
        "id": "0c2b9004-d4f0-459f-bef6-ef0320a3a352",
        "invoiceNumber": null,
        "billNumber": "1012",
        "issuedBy": "231905ef-5c5d-4426-a448-c703730e0859",
        "addedAs": "BILL",
        "issuedByCompanyName": "Aer Group Limited",
        "issuedFor": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "issuedForCompanyName": "Gla Trustee Holdings Limited",
        "jobReference": null,
        "transactionReference": null,
        "invoiceLoadedBy": null,
        "billLoadedBy": "RELAY",
        "approvalRequired": false,
        "includeInPurchaserOffer": false,
        "matched": false,
        "dueDate": 1590494400000,
        "invoiceStatus": "NO_CASHBACK",
        "billStatus": "NO_CASHBACK",
        "items": null,
        "subTotal": null,
        "gst": null,
        "total": 100,
        "totalPaid": null,
        "relayFee": null,
        "pendingAmount": null,
        "paidDate": null,
        "creationTime": 1589854259636,
        "modificationTime": 1589854259636,
        "owingCompany": {
          "id": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
          "companyName": "Gla Trustee Holdings Limited",
          "registrationNumber": "4122058",
          "industryCode": "K641965",
          "acknowledgementTimestamp": 1589768380761,
          "acknowledgementText": "By clicking confirm, you warrant that you are an authorised representative of Gla Trustee Holdings Limited and have authorisation to make payments on behalf of Gla Trustee Holdings Limited.",
          "nzbn": "9429030434806",
          "gstNumber": null,
          "website": null,
          "fundsAvailable": 0,
          "address": null,
          "status": "ACTIVE",
          "onboardedBy": "RELAY",
          "connectedToXero": false,
          "connectedToMyobEssentials": false,
          "connectedToMyobAccountRight": false,
          "xeroAccountsConfigured": false,
          "myobEssentialsAccountsConfigured": false,
          "myobAccountRightAccountsConfigured": false,
          "aliases": null,
          "verified": true,
          "invitedBy": null,
          "creationTime": 1589517979583,
          "modificationTime": 1589768380977
        },
        "companyOwed": {
          "id": "231905ef-5c5d-4426-a448-c703730e0859",
          "companyName": "Aer Group Limited",
          "registrationNumber": null,
          "industryCode": null,
          "acknowledgementTimestamp": null,
          "acknowledgementText": null,
          "nzbn": null,
          "gstNumber": null,
          "website": null,
          "fundsAvailable": 0,
          "address": null,
          "status": "INACTIVE",
          "onboardedBy": "RELAY",
          "connectedToXero": false,
          "connectedToMyobEssentials": false,
          "connectedToMyobAccountRight": false,
          "xeroAccountsConfigured": false,
          "myobEssentialsAccountsConfigured": false,
          "myobAccountRightAccountsConfigured": false,
          "aliases": [
            {
              "forCompany": "Gla Trustee Holdings Limited",
              "alias": "Aer Group Limited"
            }
          ],
          "verified": null,
          "invitedBy": null,
          "creationTime": 1589854259502,
          "modificationTime": 1589854259502
        }
      },
      "_links": {
        "self": {
          "href": "https://api.dev.relay.ai/invoice/0c2b9004-d4f0-459f-bef6-ef0320a3a352"
        },
        "companyOwed": {
          "href": "https://api.dev.relay.ai/company/231905ef-5c5d-4426-a448-c703730e0859"
        },
        "owingCompany": {
          "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
        }
      }
    },
    {},
    {}
  ]
}

Get Invoices
GET/invoice

Get all invoices

Supported Query Params Values Description
Type INVOICE,BILL Mandatory, when searching, based on the values invoices or bills are returned
LoadedBy RELAY,XERO,MYOB_ACCOUNTRIGHT,MYOB_ESSENTIALS This gives you invoices/bill which were imported or created by these systems
page integer (0-n) to get paginated response from the api, default page value is 0
size integer (1-n) to get paginated response from the api, default size is 5
sort fieldName,order (e.g dueDate,asc) to specify sorting to be done on what column and in what order, order could be asc or desc
status ALL, PAYMENT_OFFERED, CASHBACK_AVAILABLE, CASHBACK_RECEIVED, CASHBACK_OFFERED, PAYMENT_READY, PAYMENT_RECEIVED filtering invoices/bill based on status. Meaning of each status has been described below
Status Meaning
ALL Get all invoices or bills
PAYMENT_OFFERED GET all bills on which payment has been offered. A bill takes this status when a purchaserOffer is created and the bill is included
CASHBACK_AVAILABLE Get all bills on which cashback is available to be received. A bill takes this status when a supplier has offered a discount on his invoice. Resulting in purchaser getting incentivsed to pay early.
CASHBACK_RECEIVED Get all bills on which casback was received. A bill takes this status when a bill was paid on acceptance on a offer.
CASHBACK_OFFERED Get all bills on which cashback has been offered, similar to CASHBACK_AVAILABLE.
PAYMENT_READY Get all invoices for which payment is ready. A invoice takes this status when a purchaser is ready to pay a bill
PAYMENT_RECEIVED Get all invoices on which payment has been received. An invoice takes this state when the purchaser has paid his bill

Delete invoice or bill

DELETE https://api.sandbox.relay.ai/invoice/e05ad5ea
Requestswithout body
Headers
Authorization: Bearer "access_token"
Responses204
This response has no content.

Delete invoice or bill
DELETE/invoice/{id}

Delete an invoice or bill

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the invoice or bill

SupplierOffer

Below are the list of APIs that are used to do some action on the supplierOffer object

Create Supplier Offer

POST https://api.sandbox.relay.ai/company
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
  "invoiceIds": [
    "6d19e327-3f2d-4494-afab-2fd0e28d188f"
  ],
  "autobid": "10.00",
  "offerUnit": "DOLLAR",
  "expirationTime": 1590580799000
}
Responses201
Headers
Content-Type: application/json
Body
{
  "supplierOffer": {
    "id": "4220e1bf-3163-46d4-9d7b-9fc81ad883d4",
    "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
    "invoiceIds": [
      "6d19e327-3f2d-4494-afab-2fd0e28d188f"
    ],
    "autobid": 10,
    "relayFee": 0.5,
    "cashReward": 9.5,
    "offerUnit": "DOLLAR",
    "expirationTime": 1590580799000,
    "offerStatus": "CLEARING",
    "creationTime": 1589927766172,
    "modificationTime": 1589927766172
  },
  "_links": {
    "self": {
      "href": "https://api.dev.relay.ai/supplieroffer/4220e1bf-3163-46d4-9d7b-9fc81ad883d4"
    },
    "createdCompany": {
      "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
    },
    "invoice": {
      "href": "https://api.dev.relay.ai/invoice/6d19e327-3f2d-4494-afab-2fd0e28d188f"
    }
  }
}

Create Supplier Offer
POST/company

Create a supplier offer for a invoice

Field Required Description
createdByCompany Y UUID of the company creating the offer
invoiceIds Y UUID of the invoices to be included in the offer. Only one invoice Id is supported as of now
autobid Y discount offered on the invoice
offerUnit Y DOLLAR,PERCENTAGE. Only DOLLAR is supported as of now
expirationTime Y time in epoch milliseconds by when the offer will expire

Get SupplierOffer

GET https://api.sandbox.relay.ai/supplierOffer
Requestswithout body
Headers
Accept: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
{
  "pageNumber": 0,
  "pageSize": 1000,
  "totalPages": 1,
  "totalElements": 3,
  "supplierOfferResources": [
    {
      "supplierOffer": {
        "id": "73c73b7b-b57b-47f2-8397-b6ba94b0c93d",
        "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "invoiceIds": [
          "2e22e820-6a1e-45b7-9123-5de6c07992bf"
        ],
        "autobid": 10,
        "relayFee": 0.5,
        "cashReward": 9.5,
        "offerUnit": "DOLLAR",
        "expirationTime": 1590344999000,
        "offerStatus": "CLEARING",
        "creationTime": 1589864825852,
        "modificationTime": 1589864825852
      },
      "_links": {
        "self": {
          "href": "https://api.dev.relay.ai/supplieroffer/73c73b7b-b57b-47f2-8397-b6ba94b0c93d"
        },
        "createdCompany": {
          "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
        },
        "invoice": {
          "href": "https://api.dev.relay.ai/invoice/2e22e820-6a1e-45b7-9123-5de6c07992bf"
        }
      }
    },
    {
      "supplierOffer": {
        "id": "4220e1bf-3163-46d4-9d7b-9fc81ad883d4",
        "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "invoiceIds": [
          "6d19e327-3f2d-4494-afab-2fd0e28d188f"
        ],
        "autobid": 10,
        "relayFee": 0.5,
        "cashReward": 9.5,
        "offerUnit": "DOLLAR",
        "expirationTime": 1590580799000,
        "offerStatus": "CLEARING",
        "creationTime": 1589927766172,
        "modificationTime": 1589927766172
      },
      "_links": {
        "self": {
          "href": "https://api.dev.relay.ai/supplieroffer/4220e1bf-3163-46d4-9d7b-9fc81ad883d4"
        },
        "createdCompany": {
          "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
        },
        "invoice": {
          "href": "https://api.dev.relay.ai/invoice/6d19e327-3f2d-4494-afab-2fd0e28d188f"
        }
      }
    },
    {
      "supplierOffer": {
        "id": "e1a736b5-041b-4076-b590-e9339f079975",
        "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "invoiceIds": [
          "357ba438-4bed-48b1-9722-1b56a3b9579f"
        ],
        "autobid": 100,
        "relayFee": 5,
        "cashReward": 95,
        "offerUnit": "DOLLAR",
        "expirationTime": 1590580799000,
        "offerStatus": "EXPIRED",
        "creationTime": 1589928138230,
        "modificationTime": 1589928162469
      },
      "_links": {
        "self": {
          "href": "https://api.dev.relay.ai/supplieroffer/e1a736b5-041b-4076-b590-e9339f079975"
        },
        "createdCompany": {
          "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
        },
        "invoice": {
          "href": "https://api.dev.relay.ai/invoice/357ba438-4bed-48b1-9722-1b56a3b9579f"
        }
      }
    }
  ]
}

Get SupplierOffer
GET/supplierOffer

Gets supplier offer created by loggedIn company

Get Available SupplierOffer

GET https://api.sandbox.relay.ai/supplierOffer/available
Requestswithout body
Headers
Accept: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
{
  "pageNumber": 0,
  "pageSize": 1000,
  "totalPages": 1,
  "totalElements": 3,
  "supplierOfferResources": [
    {
      "supplierOffer": {
        "id": "73c73b7b-b57b-47f2-8397-b6ba94b0c93d",
        "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "invoiceIds": [
          "2e22e820-6a1e-45b7-9123-5de6c07992bf"
        ],
        "autobid": 10,
        "relayFee": 0.5,
        "cashReward": 9.5,
        "offerUnit": "DOLLAR",
        "expirationTime": 1590344999000,
        "offerStatus": "CLEARING",
        "creationTime": 1589864825852,
        "modificationTime": 1589864825852
      },
      "_links": {
        "self": {
          "href": "https://api.dev.relay.ai/supplieroffer/73c73b7b-b57b-47f2-8397-b6ba94b0c93d"
        },
        "createdCompany": {
          "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
        },
        "invoice": {
          "href": "https://api.dev.relay.ai/invoice/2e22e820-6a1e-45b7-9123-5de6c07992bf"
        }
      }
    }
  ]
}

Get Available SupplierOffer
GET/supplierOffer/available

Get supplier offers available to loggedIn company

Update SupplierOffer

PUT https://api.sandbox.relay.ai/supplieroffer/e05ad5ea
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "id": "e1a736b5-041b-4076-b590-e9339f079975",
  "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
  "invoiceIds": [
    "357ba438-4bed-48b1-9722-1b56a3b9579f"
  ],
  "autobid": 100,
  "relayFee": 5,
  "cashReward": 95,
  "offerUnit": "DOLLAR",
  "expirationTime": 1590580799000,
  "offerStatus": "EXPIRED",
  "creationTime": 1589928138230,
  "modificationTime": 1589928138230
}
Responses200
Headers
Content-Type: application/json
Body
{
  "supplierOffer": {
    "id": "e1a736b5-041b-4076-b590-e9339f079975",
    "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
    "invoiceIds": [
      "357ba438-4bed-48b1-9722-1b56a3b9579f"
    ],
    "autobid": 100,
    "relayFee": 5,
    "cashReward": 95,
    "offerUnit": "DOLLAR",
    "expirationTime": 1590580799000,
    "offerStatus": "EXPIRED",
    "creationTime": 1589928138230,
    "modificationTime": 1589928162469
  },
  "_links": {
    "self": {
      "href": "https://api.dev.relay.ai/supplieroffer/e1a736b5-041b-4076-b590-e9339f079975"
    },
    "createdCompany": {
      "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
    },
    "invoice": {
      "href": "https://api.dev.relay.ai/invoice/357ba438-4bed-48b1-9722-1b56a3b9579f"
    }
  }
}

Update SupplierOffer
PUT/supplieroffer/{id}

  • Both the company who has created the supplieroffer or the company who the supplieroffer is available to can make this call.

  • Usually this call is made by the buyer (who the supplieroffer is available to) to accept the offer i.e to update the status to EXECUTED

  • Supplier or the creator of the offer usually makes this call to either reset the offer or change the autobid amount.

A supplierOffer can go through different status as described below

Status Meaning
CLEARING The status when the supplierOffer is created and made available to the buyer associated to the invoice
EXPIRED If the supplierOffer hasnt been expected before the expirationTime or if the supplierOffer has been reseted by the supplier, then the object goes into this state
EXECUTED When the buyer accepts the supplierOffer, the offer object goes into this state
TOPUP_PENDING When the buyer accepts the supplierOffer but he doesn’t have sufficient funds, the offer goes into this state. Upon the buyer doing the topup, the offer will auto execute and the go to EXECUTED state
URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the supplieroffer

PurchaserOffer

Below are the list of APIs that are used to do some action on the purchaserOffer object

Create Purchaser Offer

POST https://api.sandbox.relay.ai/purchaseroffer
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
  "cashpool": "1000.00",
  "crr": "10",
  "expirationTime": 1621425600000,
  "invoiceIds": [
    "90c4eb09-0236-44e8-8bfc-f06d27611195"
  ]
}
Responses201
Headers
Content-Type: application/json
Body
{
  "purchaserOffer": {
    "id": "22d51923-db33-4551-b9fe-5d30d319adc6",
    "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
    "cashpool": 0,
    "pendingCashpool": 1000,
    "crr": 10,
    "expirationTime": 1621425600000,
    "offerStatus": "UNUSED",
    "creationTime": 1589930056127,
    "modificationTime": 1589930056127
  },
  "_links": {
    "self": {
      "href": "https://api.dev.relay.ai/purchaseroffer/22d51923-db33-4551-b9fe-5d30d319adc6"
    },
    "createdCompany": {
      "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
    }
  }
}

Create Purchaser Offer
POST/purchaseroffer

Create a supplier offer for a invoice

Field Required Description
createdByCompany Y UUID of the company creating the offer
invoiceIds Y UUID of the invoices to be included in the offer.
crr Y cash reserve rate
cashpool Y Funds allocated to the offer for early payment
expirationTime Y time in epoch milliseconds by when the offer will expire
pendingCashpool N If one tries to create an offer without sufficient funds in the bank account, the offer goes into TOPUP_PENDING state and pendingCashpool contains the TOPUP amount

Get PurchaserOffer

GET https://api.sandbox.relay.ai/purchaseroffer
Requestswithout body
Headers
Accept: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
{
  "pageNumber": 0,
  "pageSize": 1000,
  "totalPages": 1,
  "totalElements": 1,
  "purchaserOfferResource": [
    {
      "purchaserOffer": {
        "id": "22d51923-db33-4551-b9fe-5d30d319adc6",
        "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "cashpool": 0,
        "pendingCashpool": 1000,
        "crr": 10,
        "expirationTime": 1621425600000,
        "offerStatus": "UNUSED",
        "creationTime": 1589930056127,
        "modificationTime": 1589930056127
      },
      "_links": {
        "self": {
          "href": "https://api.dev.relay.ai/purchaseroffer/22d51923-db33-4551-b9fe-5d30d319adc6"
        },
        "createdCompany": {
          "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
        }
      }
    }
  ]
}

Get PurchaserOffer
GET/purchaseroffer

Gets purchaser offer created by loggedIn company

Get Available PurchaserOffer

GET https://api.sandbox.relay.ai/purchaserOffer/available
Requestswithout body
Headers
Accept: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
{
  "pageNumber": 0,
  "pageSize": 1000,
  "totalPages": 1,
  "totalElements": 1,
  "purchaserOfferResource": [
    {
      "purchaserOffer": {
        "id": "22d51923-db33-4551-b9fe-5d30d319adc6",
        "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
        "cashpool": 0,
        "pendingCashpool": 1000,
        "crr": 10,
        "expirationTime": 1621425600000,
        "offerStatus": "UNUSED",
        "creationTime": 1589930056127,
        "modificationTime": 1589930056127
      },
      "_links": {
        "self": {
          "href": "https://api.dev.relay.ai/purchaseroffer/22d51923-db33-4551-b9fe-5d30d319adc6"
        },
        "createdCompany": {
          "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
        }
      }
    }
  ]
}

Get Available PurchaserOffer
GET/purchaserOffer/available

Get purchaser offers available to loggedIn company

Update PurchaserOffer

PUT https://api.sandbox.relay.ai/purchaserOffer/e05ad5ea
Requestswith body
Headers
Content-Type: application/json
Authorization: Bearer "access_token"
Body
{
  "id": "22d51923-db33-4551-b9fe-5d30d319adc6",
  "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
  "cashpool": 0,
  "pendingCashpool": 1000,
  "crr": 10,
  "expirationTime": 1621425600000,
  "offerStatus": "EXPIRED",
  "creationTime": 1589930056127,
  "modificationTime": 1589930056127
}
Responses200
Headers
Content-Type: application/json
Body
{
  "purchaserOffer": {
    "id": "22d51923-db33-4551-b9fe-5d30d319adc6",
    "createdByCompany": "94068cdc-2dfb-4c16-a4e9-3bb02642df56",
    "cashpool": 0,
    "pendingCashpool": 1000,
    "crr": 10,
    "expirationTime": 1621425600000,
    "offerStatus": "EXPIRED",
    "creationTime": 1589930056127,
    "modificationTime": 1589930711056
  },
  "_links": {
    "self": {
      "href": "https://api.dev.relay.ai/purchaseroffer/22d51923-db33-4551-b9fe-5d30d319adc6"
    },
    "createdCompany": {
      "href": "https://api.dev.relay.ai/company/94068cdc-2dfb-4c16-a4e9-3bb02642df56"
    }
  }
}

Update PurchaserOffer
PUT/purchaserOffer/{id}

  • The company who has created the purchaserOffer can make this call.

  • Buyer or the creator of the offer usually makes this call to either reset the offer or change the crr or cashpool amount.

A purchaserOffer can take these states as described below

Status Meaning
UNUSED When the purchaserOffer is initially created by the buyer, it goes into this state
TOPUP_PENDING If the buyer doesnt have sufficient funds in his account, and he tries to create the offer, the offer goes into this state. Upon doing a topup, it auto-executed and the offer goes into UNUSED state
PARTIALLY_EXECUTED When the offer has been accepted by the supplier but the cashpool still has balance in it, the offer goes into PARTIALLY_EXECUTED state
EXECUTED When the suppliers have accepted the offer and the cashpool doesnt have any funds left, the offer is considered as completely executed.
EXPIRED If the buyer resets his offer, the offer moves into this state
URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the purchaserOffer

Allocate Invoice To Purchaser Offer

POST https://api.sandbox.relay.ai/purchaseroffer/e05ad5ea/allocated
Requestswith body
Headers
Accept: application/json
Authorization: Bearer "access_token"
Body
{
  "invoiceIds": [
    "e7f11ea3-a8d3-4642-9c48-0b77df5e8514"
  ]
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "7190f0d9-b304-4385-a8d9-d9a1eab94643",
  "allocatedOfferStatus": "NEW",
  "invoiceIds": [
    "0c2b9004-d4f0-459f-bef6-ef0320a3a352"
  ],
  "creationTime": 1589931804659,
  "modificationTime": 1589931804659
}

Allocate Invoice To Purchaser Offer
POST/purchaseroffer/{id}/allocated

This API is called when a supplier accepts a purchaserOffer and allocates his invoice to the offer

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the purchaserOffer

Get Allocation

GET https://api.sandbox.relay.ai/purchaseroffer/e05ad5ea/allocated/7190f0d9
Requestswithout body
Headers
Accept: application/json
Authorization: Bearer "access_token"
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "7190f0d9-b304-4385-a8d9-d9a1eab94643",
  "allocatedOfferStatus": "EXECUTED",
  "invoiceIds": [
    "0c2b9004-d4f0-459f-bef6-ef0320a3a352"
  ],
  "creationTime": 1589931804659,
  "modificationTime": 1589931804659
}

Get Allocation
GET/purchaseroffer/{id}/allocated/{allocatedId}

Call this API to get details of allocation, this will give you detail around what invoice has been allocated to the purchaserOffer for execution.

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the purchaserOffer

allocatedId
string (required) Example: 7190f0d9

b304-4385-a8d9-d9a1eab94643 (UUID) - The unique identifier of the allocated object

Update Allocation

PUT https://api.sandbox.relay.ai/purchaseroffer/e05ad5ea/allocated/7190f0d9
Requestswith body
Headers
Accept: application/json
Authorization: Bearer "access_token"
Body
{
  "id": "7190f0d9-b304-4385-a8d9-d9a1eab94643",
  "allocatedOfferStatus": "EXECUTED",
  "invoiceIds": [
    "0c2b9004-d4f0-459f-bef6-ef0320a3a352"
  ],
  "creationTime": 1589931804659,
  "modificationTime": 1589931804659
}
Responses200
Headers
Content-Type: application/json
Body
{
  "id": "7190f0d9-b304-4385-a8d9-d9a1eab94643",
  "allocatedOfferStatus": "EXECUTED",
  "invoiceIds": [
    "0c2b9004-d4f0-459f-bef6-ef0320a3a352"
  ],
  "creationTime": 1589931804659,
  "modificationTime": 1589931804659
}

Update Allocation
PUT/purchaseroffer/{id}/allocated/{allocatedId}

Immediately after allocation, we call this API for execution of offer for the allocated invoice

URI Parameters
HideShow
id
string (required) Example: e05ad5ea

c87e-4281-b7e6-38d16455b2e8 (UUID) - The unique identifier of the purchaserOffer

allocatedId
string (required) Example: 7190f0d9

b304-4385-a8d9-d9a1eab94643 (UUID) - The unique identifier of the allocated object

Revision History

This sections describes the changes to this API specification

Date Change Author Reviewed By
20/May/2020 First publication Utsav Sharma utsav@relay.ai Michael McFadden michael@relay.ai

Generated by aglio on 21 May 2020