Marketplace (beta) (2.0)

Download OpenAPI specification:Download

Capitalise: engineering@capitalise.com URL: https://capitalise.com

Overview

Marketplace V2 is redesigned to structure around tenant. Credit profile widget only supports Marketplace V2.

This suite of APIs is currently in beta. Please reach out to your Partnership Manager before migrate or using it.

Note: Marketplace V1 can be found here.

Environments

Environment	Base URL	Description
Demo	https://demo.capitalise.com	Get started with test credentials and life-like data
Production	https://capitalise.com	Launch your app with unlimited live credentials

Authentication & Authorisation concepts

Throughout the Developer Portal where Marketplace V2 is mentioned, you will see below terminology:

API Key: this is a unique key of your application to access Capitalise APIs. It is generated by Platform V1
Master (access) token: this token is used to manage tenants at tenant level, e.g. /tenants. It can't be used to manage the product and data of a specific tenant.
Tenant (access) token: this token is used to manage the product and data of a specific tenants, e.g. /profile. It can't be used to manage tenants at tenant level.

Auth

Generate a master access token for tenants management

Authorizations:

X-API-Key

header Parameters

X-API-Key

required

string

API Key

Responses

Response Schema: application/json

access_token	string The access token to manage tenants, which is referred as `Marketplace master access token` in the documentation.
expires_in	string The expiry of `access_token` in seconds
refresh_token	string The refresh token
scope	string The scopes that the tenants should have
token_type	string The token type

Response samples

201

Content type

application/json

{"access_token": "string",
"expires_in": "string",
"refresh_token": "string",
"scope": "string",
"token_type": "string"
}

Refresh a master access token

Authorizations:

Master Access Token

Request Body schema: application/json

refresh_token

string

The refresh token

Responses

Response Schema: application/json

access_token	string The access token to manage tenants, which is referred as `Marketplace master access token` in the documentation.
expires_in	string The expiry of `access_token` in seconds
refresh_token	string The refresh token
scope	string The scopes that the tenants should have
token_type	string The token type

Request samples

Payload

Content type

application/json

{"refresh_token": "string"
}

Response samples

201

Content type

application/json

{"access_token": "string",
"expires_in": "string",
"refresh_token": "string",
"scope": "string",
"token_type": "string"
}

Generate a tenant access token

Generate a tenant access token to manage products and data of a specific tenant

Authorizations:

Master Access Token

header Parameters

Capitalise-tenant-id

string

The tenant ID

Responses

Response Schema: application/json

object

Response samples

201

Content type

application/json

{ }

Profile

Retrieve the profile

Authorizations:

Tenant Access Token

Responses

Response Schema: application/json

required

object

code	string Enum: "GBP" "ZAR" The currency of the credit limit value
value	number The value of the credit limit

name

string non-empty

The name of the company

registrationNumber

string non-empty

The registration number of the company

object

grade

string non-empty

Enum: "A" "B" "C" "D" "E" "F" "G"

The credit score grade of the company

Grade	title	description
A	Minimum risk	This companty is considered as minimum risk. There is a low probability of the company going into defaul in the next 12 month. Offering credit terms to the recommended credit limit is advised. Highly likely to access finance at favourable rates
B	Low risk	This companty is considered as low risk. There is a low probability of the company going into defaul in the next 12 month. Offering credit terms to the recommended credit limit is advised. Highly likely to access finance at favourable rates
C	Below average risk	The company is consisdered as below average risk. There is a moderate probability of the company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Likely to access high value finance but a guarantee may be required
D	Above average risk	The company is consisdered as above average risk. There is a moderate probability of the company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Likely to access high value finance but a guarantee may be required
E	High risk	There company is considered as high risk and has a high probability of this company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Challenging to access finance and a personal guaranteed might be required.
F	Maximum risk	There company is considered as maximum risk and has a high probability of this company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Challenging to access finance and a personal guaranteed might be required.
G	Dissolved	There company is dissolved.

sector

string non-empty

Enum: "AGRICULTURE" "AUTOMOTIVE" "BUSINESS_SERVICES" "CHARITIES" "CONSTRUCTION" "COURIER" "DISTRIBUTION" "EDUCATION" "FINANCIAL_SERVICES" "HAULAGE" "HEALTHCARE_CARE" "HOTELS_HOUSE" "IMPORT_EXPORT" "IT_RELATED" "MANUFACTURING" "MEDIA_AND_ENTERTAINMENT" "OTHER" "PRINT_PUBLISHING" "PROFESSIONAL_SERVICES" "PROPERTY" "RECRUITMENT" "RETAIL" "SECURITY_SERVICES" "TRADE" "TRANSPORTATION" "WHOLESALE"

The sector of the company

type

string non-empty

Enum: "LIMITED_COMPANY" "LIMITED_LIABILITY_PARTNERSHIP" "SOLE_TRADER" "STARTUP"

The type of the company

createdAt

required

string non-empty

Profile created date time

id

required

string non-empty

The profile ID

updatedAt

required

string non-empty

Profile updated date time

Response samples

200

Content type

application/json

{"companyInformation": {"name": "string",
"type": "LIMITED_COMPANY",
"sector": "AGRICULTURE",
"registrationNumber": "string",
"score": {"grade": "A"
},
"creditLimit": {"value": 0,
"code": "GBP"
}
},
"id": "string",
"createdAt": "string",
"updatedAt": "string"
}

Set up profile details

Authorizations:

Tenant Access Token

Request Body schema: application/json

required

object

registrationNumber

required

string

The Companies House number

Responses

Response Schema: application/json

required

object

code	string Enum: "GBP" "ZAR" The currency of the credit limit value
value	number The value of the credit limit

name

string non-empty

The name of the company

registrationNumber

string non-empty

The registration number of the company

object

grade

string non-empty

Enum: "A" "B" "C" "D" "E" "F" "G"

The credit score grade of the company

Grade	title	description
A	Minimum risk	This companty is considered as minimum risk. There is a low probability of the company going into defaul in the next 12 month. Offering credit terms to the recommended credit limit is advised. Highly likely to access finance at favourable rates
B	Low risk	This companty is considered as low risk. There is a low probability of the company going into defaul in the next 12 month. Offering credit terms to the recommended credit limit is advised. Highly likely to access finance at favourable rates
C	Below average risk	The company is consisdered as below average risk. There is a moderate probability of the company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Likely to access high value finance but a guarantee may be required
D	Above average risk	The company is consisdered as above average risk. There is a moderate probability of the company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Likely to access high value finance but a guarantee may be required
E	High risk	There company is considered as high risk and has a high probability of this company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Challenging to access finance and a personal guaranteed might be required.
F	Maximum risk	There company is considered as maximum risk and has a high probability of this company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Challenging to access finance and a personal guaranteed might be required.
G	Dissolved	There company is dissolved.

sector

string non-empty

Enum: "AGRICULTURE" "AUTOMOTIVE" "BUSINESS_SERVICES" "CHARITIES" "CONSTRUCTION" "COURIER" "DISTRIBUTION" "EDUCATION" "FINANCIAL_SERVICES" "HAULAGE" "HEALTHCARE_CARE" "HOTELS_HOUSE" "IMPORT_EXPORT" "IT_RELATED" "MANUFACTURING" "MEDIA_AND_ENTERTAINMENT" "OTHER" "PRINT_PUBLISHING" "PROFESSIONAL_SERVICES" "PROPERTY" "RECRUITMENT" "RETAIL" "SECURITY_SERVICES" "TRADE" "TRANSPORTATION" "WHOLESALE"

The sector of the company

type

string non-empty

Enum: "LIMITED_COMPANY" "LIMITED_LIABILITY_PARTNERSHIP" "SOLE_TRADER" "STARTUP"

The type of the company

createdAt

required

string non-empty

Profile created date time

id

required

string non-empty

The profile ID

updatedAt

required

string non-empty

Profile updated date time

Request samples

Payload

Content type

application/json

{"companyInformation": {"registrationNumber": "string"
}
}

Response samples

201

Content type

application/json

{"companyInformation": {"name": "string",
"type": "LIMITED_COMPANY",
"sector": "AGRICULTURE",
"registrationNumber": "string",
"score": {"grade": "A"
},
"creditLimit": {"value": 0,
"code": "GBP"
}
},
"id": "string",
"createdAt": "string",
"updatedAt": "string"
}

Update profile

Update the profile

Request Body schema: application/json

required

object

registrationNumber

required

string

The Companies House number

Responses

Request samples

Payload

Content type

application/json

No sample

Tenants

Create a tenant

A tenant is property or product within a company.

Authorizations:

Master Access Token

Request Body schema: application/json

referenceId

string

A unique reference ID that you can pass over to identify this tenan

Responses

Response Schema: application/json

object

Request samples

Payload

Content type

application/json

{"referenceId": "string"
}

Response samples

201

Content type

application/json

{ }

Retrieve tenants

Retrieve all tenants

Authorizations:

Master Access Token

Responses

Response Schema: application/json

required

Array of objects (Profile response) non-empty unique

Array (non-empty)

required

object

code	string Enum: "GBP" "ZAR" The currency of the credit limit value
value	number The value of the credit limit

name

string non-empty

The name of the company

registrationNumber

string non-empty

The registration number of the company

object

grade

string non-empty

Enum: "A" "B" "C" "D" "E" "F" "G"

The credit score grade of the company

Grade	title	description
A	Minimum risk	This companty is considered as minimum risk. There is a low probability of the company going into defaul in the next 12 month. Offering credit terms to the recommended credit limit is advised. Highly likely to access finance at favourable rates
B	Low risk	This companty is considered as low risk. There is a low probability of the company going into defaul in the next 12 month. Offering credit terms to the recommended credit limit is advised. Highly likely to access finance at favourable rates
C	Below average risk	The company is consisdered as below average risk. There is a moderate probability of the company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Likely to access high value finance but a guarantee may be required
D	Above average risk	The company is consisdered as above average risk. There is a moderate probability of the company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Likely to access high value finance but a guarantee may be required
E	High risk	There company is considered as high risk and has a high probability of this company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Challenging to access finance and a personal guaranteed might be required.
F	Maximum risk	There company is considered as maximum risk and has a high probability of this company going into default in the next 12 months. Offering credit terms above the recommended credit limit is advised against. Challenging to access finance and a personal guaranteed might be required.
G	Dissolved	There company is dissolved.

sector

string non-empty

Enum: "AGRICULTURE" "AUTOMOTIVE" "BUSINESS_SERVICES" "CHARITIES" "CONSTRUCTION" "COURIER" "DISTRIBUTION" "EDUCATION" "FINANCIAL_SERVICES" "HAULAGE" "HEALTHCARE_CARE" "HOTELS_HOUSE" "IMPORT_EXPORT" "IT_RELATED" "MANUFACTURING" "MEDIA_AND_ENTERTAINMENT" "OTHER" "PRINT_PUBLISHING" "PROFESSIONAL_SERVICES" "PROPERTY" "RECRUITMENT" "RETAIL" "SECURITY_SERVICES" "TRADE" "TRANSPORTATION" "WHOLESALE"

The sector of the company

type

string non-empty

Enum: "LIMITED_COMPANY" "LIMITED_LIABILITY_PARTNERSHIP" "SOLE_TRADER" "STARTUP"

The type of the company

createdAt

required

string non-empty

Profile created date time

id

required

string non-empty

The profile ID

updatedAt

required

string non-empty

Profile updated date time

required

object

next	string The endpoint for the previous batch of tenants
prev	string The endpoint for the next batch of tenants
self required	string non-empty The endpoint for this request

required

object

totalEntries

required

number

Response samples

200

Content type

application/json

{"data": [{"companyInformation": {"name": "string",
"type": "LIMITED_COMPANY",
"sector": "AGRICULTURE",
"registrationNumber": "string",
"score": {"grade": "A"
},
"creditLimit": {"value": 0,
"code": "GBP"
}
},
"id": "string",
"createdAt": "string",
"updatedAt": "string"
}
],
"links": {"self": "string",
"prev": "string",
"next": "string"
},
"meta": {"totalEntries": 0
}
}