Version: 1.0

Business Registration API

Download this API's OpenAPI YAML

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.

---

Integration Options

Option 1: Interactive popup (recommended)

This approach uses Two's hosted popup to handle both returning buyers and new registrations.

Step 1: Check for existing buyer data

From your server, obtain an Autofill API delegation token (POST /autofill/v1/delegation) with read_current_buyer: true. Pass this token to the buyer's browser and call GET /autofill/v1/buyer/current with the token in the Two-Delegated-Authority-Token header. If the buyer has previously saved their details on this device, their business information is returned - use it directly without further steps.

Step 2: If no autofill data, obtain delegation tokens for the popup

From your server, request delegation tokens from both APIs:

1. Business Registration API (POST /registry/v1/delegation):

   • verify_returning_buyer: true - allows email verification of returning buyers
   • create_proposal: true - allows new buyer registration

2. Autofill API (POST /autofill/v1/delegation):

   • write_current_buyer: true - allows the popup to save buyer details on completion
   • read_current_buyer: true - allows retrieval after completion

Step 3: Open the signup popup

Pass both tokens to the buyer's browser and open a popup to https://checkout.two.inc/soletrader/signup with:

Parameter	Required	Description
authToken	Yes	Delegation token from Business Registration API
autofillToken	Yes	Delegation token from Autofill API
autofillData	No	URL-encoded JSON of buyer details to pre-populate the form
country	No	ISO 3166-1 alpha-2 code pre-selecting the registration country, e.g. US. Pass it when you already know where the buyer is registered - US buyers are asked for biometric consent, which document verification then requires.

The popup handles email verification for returning buyers, or guides new buyers through registration.

Step 4: Retrieve buyer details

When the popup closes, call GET /autofill/v1/buyer/current with your Autofill delegation token to retrieve the buyer's business details (company name, country code, organization number, addresses).

---

Option 2: Direct API integration

For full control over the user experience, integrate directly with the API endpoints.

Returning buyer flow:

Before creating a new proposal, check if the buyer already has a registered business:

1. Call POST /proposal/returning-buyer/verification with the buyer's email address
   • 201: Verification code sent - a business exists for this email
   • 404: No existing business - proceed with new registration
2. If 404, the buyer is not already registered. Skip to "New buyer registration flow".
3. If 201, prompt the buyer for the verification code and call PATCH /proposal/returning-buyer/verification
4. On success, the response contains the buyer's business details plus total_matches indicating whether more than one business is associated with this email address. If at least one match was found, a delegated auth token is provided in response header Two-Delegated-Authority-Token that grants access to GET /proposal/returning-buyer/matches/<email_address> to read the full list of associated businesses.

New buyer registration flow:

If no existing business is found:

1. Collect buyer information and POST /registry/v1/proposal
2. The proposal is created with status DRAFT
3. Optionally upload supporting evidence while in DRAFT status
4. Submit the proposal for review via the submission endpoint

Proposal lifecycle:

Status	Description
DRAFT	Initial state. Evidence can be uploaded.
SUBMITTED	Automated evaluation in progress.
IN_REVIEW	Manual review required.
ACCEPTED	Approved. Synthetic organization number generated.
DECLINED	Rejected.
WITHDRAWN	Cancelled via DELETE while SUBMITTED or IN_REVIEW.

Retrieving the organization number:

Once the proposal is accepted, Two generates a synthetic organization number. There are two ways to retrieve it:

1. Webhook (recommended): Configure a webhook to receive enrollment.approved events. The webhook payload includes the organization_number directly, eliminating the need to poll.

2. Polling: Call GET /registry/v1/proposal/<built-in function id> periodically. When status becomes ACCEPTED, the enrolled_business field will be populated with the business details including organization_number.

Use the organization number on other Two APIs (trade accounts, orders, etc.) exactly like a registered business number.

---

Notes

• During review, Two may contact the business or merchant for additional information.
• Personal information in proposals is redacted after reaching ACCEPTED or DECLINED status.
• Currently limited to UK and US sole traders only.

---

Example: Testing the Interactive Popup Flow

The following shell commands demonstrate the complete popup integration flow. Run each step individually (not as a script) to allow time for browser interactions.

Prerequisites: Set your API key as an environment variable:

AUTH_HEADERS="X-API-Key: <your sandbox api key>"
API_BASE="https://api.sandbox.two.inc"
CHECKOUT_BASE="https://checkout.sandbox.two.inc"

Step 1: Check for existing buyer data

# Back-end: Get a read token for the Autofill API

AUTOFILL_READ_TOKEN=$(curl -s "$API_BASE/autofill/v1/delegation" \
  -H "$AUTH_HEADERS" \
  -H "Content-Type: application/json" \
  -d '{"read_current_buyer": true}' \
  -D - -o /dev/null | grep -i "two-delegated-authority-token:" | cut -d' ' -f2 | tr -d '\r')

# Front-end: Check if buyer has saved details available

open "$API_BASE/autofill/v1/buyer/current?Two-Delegated-Authority-Token=$AUTOFILL_READ_TOKEN"

If a 404 is returned, the buyer has no saved data. Proceed to Step 2.

Step 2: Open the signup popup

# Back-end: Get tokens for registration and autofill write access

AUTH_TOKEN=$(curl -s "$API_BASE/registry/v1/delegation" \
  -H "$AUTH_HEADERS" \
  -H "Content-Type: application/json" \
  -d '{"verify_returning_buyer": true, "create_proposal": true}' \
  -D - -o /dev/null | grep -i "two-delegated-authority-token:" | cut -d' ' -f2 | tr -d '\r')

AUTOFILL_WRITE_TOKEN=$(curl -s "$API_BASE/autofill/v1/delegation" \
  -H "$AUTH_HEADERS" \
  -H "Content-Type: application/json" \
  -d '{"write_current_buyer": true}' \
  -D - -o /dev/null | grep -i "two-delegated-authority-token:" | cut -d' ' -f2 | tr -d '\r')

# Front-end: Open the signup popup (complete the flow in the browser)

open "$CHECKOUT_BASE/soletrader/signup?authToken=$AUTH_TOKEN&autofillToken=$AUTOFILL_WRITE_TOKEN"

The popup will:

1. Ask for the buyer's email and send a verification code
2. If a registered business is found, save details to Autofill and close
3. Otherwise, guide the buyer through registration, then save and close

Step 3: Retrieve the buyer's details

# Front-end: After the popup closes, call autofill again (reusing the existing read token)

open "$API_BASE/autofill/v1/buyer/current?Two-Delegated-Authority-Token=$AUTOFILL_READ_TOKEN"

Interpreting the result:

• 200 with data: Business details retrieved successfully. Use organization_number, country_code and company_name to place orders.
• 404: The buyer either cancelled, was rejected, or registration is still pending review.

Environments

Testing

https://api.sandbox.two.inc

Note: Read about our sandbox environment specific behaviour.

Production

https://api.two.inc

Authentication

API Key: X-Api-Key

For instructions on how to obtain API keys, visit this page. You will obtain two different keys, an initial one for testing in our sandbox environment and once ready, for production. Your API keys enables others to act on your behalf if they are able to obtain them, so make sure to keep them safe. Your API key is not to be shared with anyone, including in your version control system, client-side code, in public chatrooms and so on. The API key is applied in the request header. For example:

GET /something
X-Api-Key: secret_test_aabbccddeeff0123456789

API Keys have the following structure: secret_<env>_<key> where:

• env is determined by the environment (prod for production, test for test environments)
• key is a random, URL-safe, 64-bit encoded text string containing 32 random bytes.

Security Scheme Type:	apiKey
Header parameter name:	X-Api-Key