Hosted Onboarding API

Overview

Outpost Hosted Onboarding lets you onboard your existing merchants to Outpost services with minimal merchant friction. You retain full control over the merchant relationship, entry point, and checkout experience. Outpost provides the onboarding infrastructure, review workflow, and operations underneath.

Build with AI

Copy the full integration brief and paste it into your AI coding assistant to scaffold the integration automatically.

One-click brief for your AI agent.

Integration Flow

Your System→Outpost API→Hosted UI→Outpost Ops

You initiate — Call the Outpost API with the merchant's company data to create an onboarding application
Merchant completes — Redirect the merchant to the Outpost-hosted onboarding UI where they fill in product-specific details and submit
Outpost reviews — Outpost reviews the application asynchronously and approves or rejects it. You poll the application status

Base URL

Environment	Base URL
Staging	https://partner.outpostnow.tech
Production	https://partner.outpostanywhere.com

All endpoints use the /partner/api prefix.

Authentication

All Partner API requests require authentication using a JWT Bearer token provided in the Authorization header.

Request Header

Authorization: Bearer <your_access_api_token>

Key Points

Create and manage your API credentials (client ID and client secret) in the Partner Portal
You can have up to 2 active API credentials at a time, supporting safe key rotation
Include the JWT Bearer token in the Authorization header of every request
Keep your API credentials secure — do not expose them in client-side code or public repositories

Example Request

# Include your JWT Bearer token in every request
curl -X GET "https://partner.outpostanywhere.com/partner/api/onboarding/applications/{applicationId}" \
  -H "Authorization: Bearer $API_TOKEN"

Initiate Onboarding

POST/partner/api/onboarding/initiate

Creates a new onboarding application for a merchant, or resumes an existing one. This endpoint is idempotent: calling it again with the same merchantReference and productCode returns the existing application.

Request Headers

Parameter	Type	Required	Description
Authorization	—	Yes	Bearer token for authentication
Content-Type	—	Yes	application/json

Request Body Parameters

Parameter	Type	Required	Description
merchantReference	string	Yes	Your unique identifier for this merchant
productCode	string	Yes	Product to onboard for (e.g., tor for Tax of Record)
mode	string	No	Onboarding mode. Use HOSTED
returnUrl	string	No	URL to redirect the merchant after completing hosted onboarding
company	object	Yes	Merchant company information
company.legalName	string	Yes	Legal entity name
company.tradingName	string	No	Trading or brand name
company.website	string	Yes	Company website URL
company.taxId	string	Yes	Tax identification number (e.g., VAT number)
company.registrationNumber	string	Yes	Company registration number
company.jurisdiction	string	Yes	Country of incorporation (ISO 3166-1 alpha-2)
company.gmvTier	string	No	Gross Merchandise Volume tier
company.registeredAddress	object	Yes	Registered business address
company.registeredAddress.line1	string	Yes	Primary address line
company.registeredAddress.line2	string	No	Secondary address line
company.registeredAddress.city	string	Yes	City
company.registeredAddress.state	string	No	State or province
company.registeredAddress.postalCode	string	Yes	Postal or ZIP code
company.registeredAddress.country	string	Yes	ISO 3166-1 alpha-2 country code
complianceSummary	object	No	Pre-existing compliance data from your KYC process
merchantContext	map	No	Arbitrary key-value metadata about the merchant

Response 200 OK

{
  "applicationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "DRAFT",
  "mode": "HOSTED",
  "isExistingApplication": false,
  "onboardingUrl": "https://onboarding.outpostanywhere.com/your-company/onboarding?app=f47ac10b-...&token=..."
}

Response Fields

Parameter	Type	Required	Description
applicationId	string	—	Unique identifier for the onboarding application (UUID)
status	string	—	Current application status
mode	string	—	Onboarding mode (HOSTED)
isExistingApplication	boolean	—	true if an existing application was returned
onboardingUrl	string	—	Hosted onboarding URL to redirect the merchant to

Error Responses

HTTP	Code	Description
400	invalid_argument	Missing or invalid required company fields

Code Example

curl -X POST "https://partner.outpostanywhere.com/partner/api/onboarding/initiate" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantReference": "mrc_123456",
    "productCode": "tor",
    "mode": "HOSTED",
    "returnUrl": "https://your-app.example.com/onboarding/complete",
    "company": {
      "legalName": "Acme Digital Ltd",
      "tradingName": "Acme",
      "website": "https://acme.example",
      "taxId": "GB123456789",
      "registrationNumber": "12345678",
      "jurisdiction": "GB",
      "registeredAddress": {
        "line1": "1 Example Street",
        "city": "London",
        "postalCode": "EC1A 1AA",
        "country": "GB"
      }
    }
  }' | jq

Get Application

GET/partner/api/onboarding/applications/{applicationId}

Retrieves the current state of an onboarding application. Use this endpoint to poll for status changes after the merchant has been redirected to the hosted onboarding UI. Recommended polling interval: 30-60 seconds.

Response Fields

Parameter	Type	Required	Description
applicationId	string	—	Unique identifier (UUID)
status	string	—	Current status (DRAFT, IN_REVIEW, APPROVED, REJECTED, CHANGES_REQUESTED)
mode	string	—	Onboarding mode (HOSTED)
partnerId	string	—	Your partner identifier
partnerMerchantId	string	—	The merchantReference you provided at initiation
productId	string	—	Product code (e.g., tor)
company	object	—	Merchant company information provided at initiation
selectedRegions	string[]	—	Regions selected by the merchant
businessDescription	string	—	Merchant's business description
storeUrls	string[]	—	Merchant's store or checkout URLs
audit	object	—	Timestamps for application lifecycle events
audit.createdAt	string	—	ISO 8601 timestamp when the application was created
audit.updatedAt	string	—	ISO 8601 timestamp of the last update
audit.submittedAt	string	—	Timestamp when merchant submitted (null if not yet)
audit.reviewedAt	string	—	Timestamp when Outpost reviewed (null if not yet)
audit.reviewMessage	string	—	Reviewer message (e.g., rejection reason, requested changes)

Response 200 OK

{
  "applicationId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "status": "DRAFT",
  "mode": "HOSTED",
  "partnerId": "partner_example",
  "partnerMerchantId": "mrc_123456",
  "productId": "tor",
  "company": {
    "legalName": "Acme Digital Ltd",
    "jurisdiction": "GB",
    "...": "..."
  },
  "selectedRegions": [
    "GB",
    "DE"
  ],
  "businessDescription": "Subscription software for finance teams",
  "storeUrls": [
    "https://acme.example/checkout"
  ],
  "audit": {
    "createdAt": "2026-03-17T10:00:00Z",
    "updatedAt": "2026-03-17T11:00:00Z",
    "submittedAt": null,
    "reviewedAt": null,
    "reviewMessage": null
  }
}

Error Responses

HTTP	Code	Description
400	missing_applicationId	Invalid or missing applicationId path parameter
404	not_found	Application not found or does not belong to your account

Code Example

curl "https://partner.outpostanywhere.com/partner/api/onboarding/applications/{applicationId}" \
  -H "Authorization: Bearer $API_TOKEN" | jq

Update Application

PATCH/partner/api/onboarding/applications/{applicationId}

Updates merchant-editable fields on a draft application. Use this to pre-fill data before the merchant visits the hosted onboarding UI, or to update data after Outpost has requested changes. Only allowed when status is DRAFT or CHANGES_REQUESTED.

Request Body (all fields optional)

Parameter	Type	Required	Description
selectedRegions	string[]	No	ISO 3166-1 alpha-2 country codes for desired regions
businessDescription	string	No	Description of the merchant's business
storeUrls	string[]	No	Merchant's store or checkout URLs
category	string	No	Business category

Returns the full application state (same structure as Get Application).

Error Responses

HTTP	Code	Description
400	missing_applicationId	Invalid or missing applicationId
404	not_found	Application not found or does not belong to your account
409	invalid_status	Application is not in DRAFT or CHANGES_REQUESTED status

Code Example

curl -X PATCH "https://partner.outpostanywhere.com/partner/api/onboarding/applications/{applicationId}" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "selectedRegions": ["GB", "DE", "FR"],
    "businessDescription": "SaaS platform for finance teams",
    "storeUrls": ["https://acme.example/checkout"]
  }' | jq

Regenerate Link

POST/partner/api/onboarding/applications/{applicationId}/regenerate-link

Generates a new hosted onboarding URL for an application. Use this when the previous hosted token has expired (tokens are valid for 30 minutes) or when you need to re-send the onboarding link to the merchant.

Response 200 OK

{
  "onboardingUrl": "https://onboarding.outpostanywhere.com/your-company/onboarding?app=f47ac10b-...&token=..."
}

Response Fields

Parameter	Type	Required	Description
onboardingUrl	string	—	New hosted onboarding URL with a fresh token

Error Responses

HTTP	Code	Description
400	missing_applicationId	Invalid or missing applicationId
404	not_found	Application not found or does not belong to your account
409	terminal_status	Application is in a terminal status (APPROVED or REJECTED)

Code Example

curl -X POST "https://partner.outpostanywhere.com/partner/api/onboarding/applications/{applicationId}/regenerate-link" \
  -H "Authorization: Bearer $API_TOKEN" | jq

Application Status Lifecycle

Onboarding applications progress through these statuses. Terminal statuses (APPROVED and REJECTED) cannot be modified or regenerated.

Status Transitions

DRAFT ──[merchant submits]──> IN_REVIEW
                                │
             ┌──────────────────┼──────────────────┐
             │                  │                   │
             ▼                  ▼                   ▼
       CHANGES_REQUESTED     APPROVED            REJECTED
             │              (terminal)           (terminal)
             │
             └──[merchant resubmits]──> IN_REVIEW

Statuses

Status	Description
DRAFT	Application created but not yet submitted by the merchant
IN_REVIEW	Merchant has submitted, Outpost is reviewing
CHANGES_REQUESTED	Outpost requested changes; the merchant can update and resubmit
APPROVED	Application approved by Outpost (terminal)
REJECTED	Application rejected by Outpost (terminal)

Who Triggers Each Transition

Transition	Triggered By
DRAFT → IN_REVIEW	Merchant, via the hosted onboarding UI
IN_REVIEW → APPROVED	Outpost operations team
IN_REVIEW → REJECTED	Outpost operations team
IN_REVIEW → CHANGES_REQUESTED	Outpost operations team
CHANGES_REQUESTED → IN_REVIEW	Merchant, via the hosted onboarding UI

What You Should Do at Each Status

Status	Your Action
DRAFT	Wait for the merchant to visit the hosted URL and submit. Optionally pre-fill data via PATCH.
IN_REVIEW	No action needed. Wait for Outpost review.
CHANGES_REQUESTED	Notify the merchant. Check audit.reviewMessage for details. Regenerate the link if expired.
APPROVED	Merchant is approved. Proceed with activation in your system.
REJECTED	Notify the merchant. Check audit.reviewMessage for the reason.

Data Models

Reference for the data structures used in onboarding API requests and responses.

OnboardingCompany

Parameter	Type	Required	Description
legalName	string	Yes	Legal entity name
tradingName	string	No	Trading or brand name
website	string	Yes	Company website URL
taxId	string	Yes	Tax identification number
registrationNumber	string	Yes	Company registration number
jurisdiction	string	Yes	Country of incorporation (ISO 3166-1 alpha-2)
gmvTier	string	No	Gross Merchandise Volume tier
registeredAddress	OnboardingAddress	Yes	Registered business address

OnboardingAddress

Parameter	Type	Required	Description
line1	string	Yes	Primary address line
line2	string	No	Secondary address line
city	string	Yes	City
state	string	No	State or province
postalCode	string	Yes	Postal or ZIP code
country	string	Yes	ISO 3166-1 alpha-2 country code

PartnerComplianceSummary

Parameter	Type	Required	Description
verificationStatus	string	No	Your verification status for this merchant
riskLevel	string	No	Your risk assessment level
countryOfIncorporation	string	No	Country of incorporation from your records
hasOpenComplianceFlags	boolean	No	Whether there are open compliance flags

OnboardingGmvTier

Value	Description
UP_TO_100K	Up to $100K annual GMV
FROM_100K_TO_250K	$100K to $250K
FROM_250K_TO_500K	$250K to $500K
FROM_500K_TO_1M	$500K to $1M
FROM_1M_TO_10M	$1M to $10M
FROM_10M_TO_50M	$10M to $50M
FROM_50M_TO_100M	$50M to $100M
FROM_100M_TO_250M	$100M to $250M
FROM_250M_TO_500M	$250M to $500M
FROM_500M_TO_1B	$500M to $1B

PartnerAuditResponse

Parameter	Type	Required	Description
createdAt	string	—	ISO 8601 timestamp when the application was created
updatedAt	string	—	ISO 8601 timestamp of the last update
submittedAt	string	—	Timestamp when the merchant submitted (null if not yet)
reviewedAt	string	—	Timestamp when Outpost reviewed (null if not yet)
reviewMessage	string	—	Reviewer's message (e.g., rejection reason, requested changes)

Error Handling

All error responses follow a consistent structure with a category code and field-specific error details.

Error Response Format

{
  "code": "invalid_argument",
  "errors": [
    {
      "field": "company.legalName",
      "message": "required"
    }
  ]
}

Error Codes

Code	Description
invalid_argument	One or more request fields are invalid or missing
not_found	The requested application was not found or does not belong to your account
invalid_status	The application is not in a status that allows the requested operation
terminal_status	The application is in a terminal status and cannot be modified
incomplete_application	The application is missing required fields and cannot be submitted

Common Error Scenarios

Scenario	Status	Code	Resolution
Missing required company fields at initiation	400	invalid_argument	Include all required fields in the company object
Application not found	404	not_found	Verify the applicationId and ensure it belongs to your account
Updating an application in review	409	invalid_status	You can only update applications in DRAFT or CHANGES_REQUESTED status
Regenerating link for approved/rejected app	409	terminal_status	Terminal applications cannot be modified. Create a new application if needed

Required Fields for Submission

Before the merchant can submit the application in the hosted UI, these fields must be filled (by the merchant or pre-filled by you via PATCH):

Field	Description
selectedRegions	At least one region must be selected
businessDescription	Business description must be provided
storeUrls	At least one store or checkout URL must be provided

Ready to integrate?

Copy the complete integration plan for your AI coding assistant, or contact us for white-glove onboarding.

One-click brief for your AI agent.