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

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 - use them directly

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.

---

• 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.

---

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.

Testing

https://api.sandbox.two.inc

Note: Read about our sandbox environment specific behaviour.

Production

https://api.two.inc