Business Registration API (1.0)

Download OpenAPI specification:Download

API for enrolling businesses that do not appear in national registries, e.g. sole traders and government departments.

To create trade accounts or orders for such businesses, a proposal must first be created and then submitted via this API for Two to enrol the business.

A newly created proposal will have a status of DRAFT. In this status it is possible to upload supporting evidence. Once all evidence has been uploaded, the proposal must be submitted for review to begin. Posting to the submission endpoint causes the proposal status to progress to SUBMITTED.

Once a proposal reaches SUBMITTED status, an initial automated evaluation is undertaken. This may result in immediate approval or rejection. If, however, manual review is to be undertaken, the proposal's status will update to IN_REVIEW. Once all required review stages are complete (or if the initial automated evaluation resulted in immediate approval or rejection), the proposal status will update to ACCEPTED or DECLINED. Alternatively the proposal status will be updated to WITHDRAWN if a DELETE operation is performed on it while its status is IN_REVIEW or SUBMITTED.

During review, Two may reach out to the business described within the proposal (via the email address and phone number provided within the proposal), or to the merchant who raised the proposal, for more information.

Once a proposal has been accepted, Two will generate a synthetic organization number for the business in question and update the proposal record accordingly. This synthetic organization number may then be used by the merchant on other Two APIs in exactly the same way as for an actual registered business to create trade accounts, place orders, etc on behalf of the business.

Completion of review stages and subsequent creation of an organization number will be communicated back to the initiating merchant via webhooks.

Proposal creation and submission may be undertaken either by calling this API with the merchant's API key, or else via the delegated authority route which allows browser-side scripts to invoke this API on the merchant's behalf. To use this option, first POST to the delegation endpoint and pass the resulting header token back to the browser; then the browser may POST to /proposal with that token in a request header. A replacement token will be returned from the proposal creation operation with authority to track, withdraw and submit the newly created proposal.

Note that proposals may include personal information about people associated with the business. Once a proposal has been either accepted or declined, that personal information is no longer visible through this API.

Also note that the docs below include reference to government departments to illustrate how this API will handle different types of business, and also that the docs below include a country code for enrollment of businesses of any nationality; however implementation is for the time being limited to UK and US sole traders only.

Environments

Testing

https://api.sandbox.two.inc

Note: Read about our sandbox environment specific behaviour.

Production

https://api.two.inc

Business Registration

Create proposal

Create a new proposal for a business to be enrolled with Two, or for an existing enrollment to be updated. If this operation is authorized by a delegated authority token (generated via POST .../delegation with a body of {"create_proposal": true} and passed as a request header called Two-Delegated-Authority-Token) rather than by the merchant's API key, the response will include a new delegated authority token as a response header called Two-Delegated-Authority-Token which may be used to track (GET .../proposal/<id>), withdraw (DELETE .../proposal/<id>) or submit (POST .../proposal/<id>/submission) the newly created proposal.

SecurityX-Api-Key
Request
header Parameters
Idempotency-Key (string) or Idempotency-Key (null) (Idempotency-Key)
Default: null
Request Body schema: application/json
required
any (Proposed Business)

Details of the business that is being proposed for enrollment or update

Responses
202

Proposal has been accepted for review.

400

Proposal is invalid.

post/registry/v1/proposal
Request samples
application/json
{
  • "proposed_business": {
    }
}
Response samples
application/json
{
  • "id": null,
  • "proposed_business": {
    },
  • "enrolled_business": null,
  • "status": "DRAFT"
}

Get proposals

Get all matching proposals. At least one search parameter must be provided. Note that each merchant may only access proposals lodged by the same merchant. Also note that supplementary information is only included for proposals that have not yet been accepted, declined or withdrawn.

SecurityX-Api-Key
Request
query Parameters
BusinessTypeEnum (string) or null
Default: null
CountryCodeEnum (string) or null
Default: null
Email (string) or Email (null) (Email)
Default: null

Exact match only.

Limit (integer) or Limit (null) (Limit)
Default: null

The maximum number of items on a single page, ie the page size.

order_by
string (ProposalSearchOrderByEnum)
Default: "date_created"

How to order the search results

Enum: "status" "trading_name" "date_created" "date_updated"
order_desc
boolean (Order Desc)
Default: false

If true, reverse the results order.

Page (integer) or Page (null) (Page)
Default: null

The requested page number, 1-based.

Phone (string) or Phone (null) (Phone)
Default: null

Exact match only.

ProposalStatusEnum (string) or null
Default: null

If omitted, will return proposals that currently require action.

Trading Name (string) or Trading Name (null) (Trading Name)
Default: null

Case-insensitive partial match.

Responses
200

Proposals

get/registry/v1/proposal
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": {
    }
}
Get proposal
Get an existing proposal by id. Note that each merchant may only access proposals lodged by the same merchant. Also note that supplementary information is only included for proposals that have not yet been accepted, declined or withdrawn.


Request 
path Parameters
proposal_id
required
string
The id of an existing proposal.


 
Responses 
200
Proposal


404
Proposal not found


get/registry/v1/proposal/{proposal_id}
Request samples 
Response samples 
application/json
{
  • "id": null,
  • "proposed_business": {
    },
  • "enrolled_business": null,
  • "status": "DRAFT"
}
Withdraw proposal
Withdraw an existing proposal by id. Withdrawals will only be accepted for proposals with a status of IN_REVIEW. Withdrawal will not delete the proposal record but will instead update its status to WITHDRAWN after which no further updates will be possible. Withdrawal attempts will result in a 409 response if the proposal has already been approved or declined. Subsequent attempts to withdraw the same proposal will not prompt any action, and will result in a 200 status. Note that each merchant may only withdraw proposals lodged by that same merchant.


Request 
path Parameters
proposal_id
required
string
The id of an existing proposal.


 
Responses 
200
Proposal


404
Proposal not found


409
Proposal is not in a suitable state for withdrawals


delete/registry/v1/proposal/{proposal_id}
Request samples 
Response samples 
application/json
{
  • "id": null,
  • "proposed_business": {
    },
  • "enrolled_business": null,
  • "status": "DRAFT"
}
Submit proposal
Submit an existing proposal for review, by id. Submissions will only be accepted for proposals with a status of DRAFT. Submission attempts will result in a 200 response but take no action if the proposal has already progressed beyond DRAFT.


Request 
path Parameters
proposal_id
required
string
The id of an existing proposal.


 
Request Body schema: application/json
optional
initiation_method
string (Initiation Method) 
 Default:  "REDIRECT"
How to direct the buyer to begin verification.


 Enum: "EMAIL" "REDIRECT"  
Responses 
200
Proposal


404
Proposal not found


409
Proposal is not in a suitable state for submission


post/registry/v1/proposal/{proposal_id}/submission
Request samples 
application/json
{
  • "initiation_method": "EMAIL"
}
Response samples 
application/json
{
  • "initiation_method": "EMAIL",
  • "proposal_id": "The id of the proposal for which verification has been initiated."
}
Get businesses
Get all matching businesses that have previously been enrolled with Two via completed proposals. At least one search parameter must be provided. Note that each merchant may only access businesses referred to by accepted proposals lodged by the same merchant.


SecurityX-Api-Key 
Request 
query Parameters
BusinessTypeEnum (string) or null
 Default:  null
 
CountryCodeEnum (string) or null
 Default:  null
 
Email (string) or Email (null) (Email) 
 Default:  null
Exact match only.


 
Limit (integer) or Limit (null) (Limit) 
 Default:  null
The maximum number of items on a single page, ie the page size.


 
order_by
string (BusinessSearchOrderByEnum) 
 Default:  "date_created"
How to order the search results


 Enum: "organization_number" "trading_name" "date_created" "date_updated"  
order_desc
boolean (Order Desc) 
 Default:  false
If true, reverse the results order.


 
Organization Number (string) or Organization Number (null) (Organization Number) 
 Default:  null
Exact match only.


 
Page (integer) or Page (null) (Page) 
 Default:  null
The requested page number, 1-based.


 
Phone (string) or Phone (null) (Phone) 
 Default:  null
Exact match only.


 
Trading Name (string) or Trading Name (null) (Trading Name) 
 Default:  null
Case-insensitive partial match.


 
Responses 
200
Matching businesses


400
Parameters are invalid.


get/registry/v1/business
Request samples 
Response samples 
application/json
{
  • "items": [
    ],
  • "page": {
    }
}
Get business
Get a business that has previously been enrolled with Two via a completed proposal. Note that each merchant may only access businesses referred to by accepted proposals lodged by the same merchant.


SecurityX-Api-Key 
Request 
path Parameters
business_id
required
string
The id of a business that was enrolled as the result of an accepted proposal.


 
Responses 
200
Business


404
Business not found


get/registry/v1/business/{business_id}
Request samples 
Response samples 
application/json
{
  • "business_type": "SOLE_TRADER",
  • "country_code": "AT",
  • "trading_name": "string",
  • "website": null,
  • "email": "string",
  • "phone": "string",
  • "tax_number": null,
  • "business_address": {
    },
  • "id": "string",
  • "organization_number": "string"
}
Check validity of a browser delegation token
Checks the validity of a browser delegation token, returning the token data if valid.


Responses 
200
Delegated authority token data in the response body


401
Invalid request, for instance if provided Two-Delegated-Authority-Token has expired


get/registry/v1/delegation
Request samples 
Create a browser delegation token
Create a token for use within a buyer's browser. The token is returned as a response header called Two-Delegated-Authority-Token. To use the token, browser-side code should simply add the header to the relevant requests. The token will grant access for 1 hour, for the user's browser to impersonate the merchant for the operations associated with each role specified in the body of this request. No other operations will be possible.


Request 
Request Body schema: application/json
create_proposal
boolean (Create Proposal) 
 Default:  true
This role allows the token bearer to create new proposals.


 
Responses 
200
Delegated authority token created and returned in response header named Two-Delegated-Authority-Token


400
Invalid request, for instance no roles specified.


post/registry/v1/delegation
Request samples 
application/json
{
  • "create_proposal": true
}