New Sales API

Introduction

The ArchPay New Sales API lets an authorized partner organization submit vehicle and home warranty sales (service contracts) with their payment plans, programmatically, over HTTPS.

Business objective. Replace manual / batch sale entry with a validated, real-time API so partner organizations can submit a sale, have it checked against Arch's business rules immediately, collect any due-now payment, and book the resulting contract. The API is the single front door for new-sale intake.

What the API does

• Authenticates the calling organization with OAuth 2.0 client credentials.
• Accepts a single sale (POST /v1/sales) or up to 100 sales in one call (POST /v1/sales/batch).
• Validates each sale in stages: request format and cross-field structure, then identity and duplicate checks, then business math and date rules.
• For payment plans that move money at sale time, charges the card through Arch's payment processor before the sale is booked.
• Returns a precise, coded result for every sale, including warnings that do not block booking.

API Overview

Endpoint summary

Authentication & Authorization

Mechanism

The API uses the OAuth 2.0 client credentials grant. Your organization is issued a client_id and client_secret. You exchange them at the token endpoint for a short-lived JWT access token, then send that token as a bearer credential on every sales request.

Obtaining a token

Send a form-encoded POST to /v1/oauth/token:

Example request

curl -X POST https://api-sandbox.archcrm.com/v1/oauth/token \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Success response (HTTP 200)

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 1800
}

Using the token

Send the token in the Authorization header on every call to /v1/sales and /v1/sales/batch:

Authorization: Bearer {access_token}

In sandbox and production, every request additionally carries the Ocp-Apim-Subscription-Key header issued during onboarding, one key per environment (see API Overview).

A missing, malformed, expired, or otherwise invalid token is answered with HTTP 401, header WWW-Authenticate: Bearer, and the body {"status":"rejected","requestId":"...","error":"invalid_token"}.

Token lifecycle

• Lifetime: 30 minutes. There is no refresh token in the client-credentials grant; request a new token when the current one nears expiry.
• Caching: reuse a token until it is close to expiring rather than minting one per request.
• Revocation: tokens are not individually revocable and there is no introspection endpoint. Deactivating a client stops new tokens from being issued; an already-issued token remains valid until it expires. The short lifetime bounds exposure.

Authorization model (organization → producers)

Your token represents your organization (an Arch tenant), not an individual producer. An organization owns one or more producer codes. Every sale names a producerCode, and the API verifies that the named producer is authorized for your organization. A sale that uses a producer code not mapped to your organization is rejected with 50009 PRODUCER_NOT_AUTHORIZED.

Security considerations

• Store the client_secret in a secret manager; never embed it in client-side code or commit it to source control.
• All traffic must use HTTPS (TLS 1.2+). Plain HTTP is refused.
• Secrets are stored by Arch as salted PBKDF2-SHA256 hashes; they cannot be recovered, only reset.
• Card data is passed through to the payment processor and tokenized (vaulted); ArchPay does not store raw PANs. CVV is not collected.
• Treat the gateway subscription key like a secret too: keep it server-side, never in browser or mobile code.

Gateway Subscription Key

Sandbox and production traffic enters through Azure API Management (the API gateway). The gateway admits only requests that carry a valid subscription key.

Gateway responses

These come from the gateway, not the API, so their body shape differs from the API's {"status":"rejected",...} envelope and they carry no requestId.

POST /v1/oauth/token

Exchanges client credentials for a bearer access token. See Authentication for the parameter table and a request/response example.

Responses

POST /v1/sales

Purpose. Submit a single sale for validation, payment (if due now), and booking.

Request

Example request (Auto, financed / NonMTM, paid by card)

curl -X POST https://api-sandbox.archcrm.com/v1/sales \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
  "sale": {
    "saleType": 2,
    "contractNumber": "H612718768",
    "producerCode": 3046,
    "administratorCode": 1002,
    "insuranceCarrierCode": 2010,
    "saleDate": "2026-06-10"
  },
  "coverage": {
    "termMonths": 60,
    "effectiveDate": "2026-06-15",
    "expirationDate": "2031-06-15",
    "administratorCost": 955.00
  },
  "vehicle": {
    "vin": "1HGCM82633A004352",
    "year": 2019, "make": "Honda", "model": "Accord",
    "termMiles": 36000, "saleOdometer": 42500,
    "effectiveOdometer": 42500, "expiryOdometer": 78500
  },
  "primaryContractHolder": {
    "firstName": "Jane", "lastName": "Doe",
    "phone": "3125551212", "email": "jane@example.com", "preferredLanguage": 1
  },
  "addresses": {
    "mailing":  {"line1":"33 W Delaware Pl","line2":"Apt 6A","city":"Chicago","state":"IL","zipCode":"60610"},
    "billing":  {"line1":"33 W Delaware Pl","city":"Chicago","state":"IL","zipCode":"60610"}
  },
  "paymentPlan": {
    "retailCost": 4000.00, "downPayment": 200.00,
    "downPaymentProcessMethod": 1, "startingBalance": 3800.00,
    "installmentStartDate": "2026-07-01", "billingCycle": 1,
    "numberOfInstallments": 24, "installmentAmount": 158.33,
    "paymentMethod": 1
  },
  "paymentInstrument": {
    "card": {"holderName":"Jane Doe","number":"4111111111111111","expiration":"08/2028"}
  }
}'

Success response

{
  "status": "accepted",
  "requestId": "a1b2c3d4e5f6a7b8",
  "contractId": 90432,
  "contractNumber": "H612718768",
  "warnings": []
}

Rejection responses

Example rejection (HTTP 422)

{
  "status": "rejected",
  "requestId": "a1b2c3d4e5f6a7b8",
  "contractNumber": "H612718768",
  "errors": [
    {"code": 50117, "field": "addresses.mailing.zipCode", "message": "must be 5 digits"},
    {"code": 50207, "field": "paymentPlan.startingBalance", "message": "must equal retailCost minus downPayment"}
  ],
  "warnings": []
}

contractNumber is echoed back on rejections too (normalized); it is null when the body was unreadable.

All independent violations found in one pass are returned together so they can be fixed in a single round trip. See the Error Catalog for validation ordering and every code.

POST /v1/sales/batch

Purpose. Submit 1 to 100 sales in one call. Each row is validated, charged, and booked independently (partial success): one bad row never blocks its neighbors.

Request headers

Same as /v1/sales: Ocp-Apim-Subscription-Key, Authorization: Bearer {access_token}, and Content-Type: application/json.

Request body

{ "sales": [ { /* sale object */ }, { /* sale object */ } ] }

Success response (HTTP 200)

{
  "requestId": "a1b2c3d4e5f6a7b8",
  "summary": { "submitted": 2, "accepted": 1, "rejected": 1 },
  "results": [
    {"index": 0, "contractNumber": "H612718768", "status": "accepted", "contractId": 90432, "errors": [], "warnings": []},
    {"index": 1, "contractNumber": "H612718768", "status": "rejected", "errors": [ ... ], "warnings": []}
  ]
}

HTTP status semantics

GET /health

Purpose. Liveness/readiness probe; no OAuth bearer token is required. Note: no /v1 prefix. HEAD /health is also accepted (same status, empty body) for uptime monitors. The gateway subscription key is still required — a keyless request is rejected 401 at the gateway.

GET https://api-sandbox.archcrm.com/health
Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY

200 OK
{ "status": "ok", "environment": "sandbox" }

Data Models & Enums

The sale request is a single JSON object with nested sections. Field names are camelCase. Unknown fields are rejected (a typo'd field name is an error — 50101), not ignored. Strings are trimmed. Money fields are decimals with at most 2 decimal places (and at most 12 digits in total); send them as JSON numbers (for example 955.00).

Top-level structure

The sale type drives everything

saleType selects the product family (Auto vs Home) and the financing style (MTM vs NonMTM), which in turn decide which sections and fields are required or forbidden.

• MTM (Month-to-Month): a recurring plan with an activationFee; the financed-purchase fields are not used.
• NonMTM (Financed / Termed): a retail cost financed over a fixed number of installments, with a derived starting balance.

Conditional field matrix

Field reference

sale

coverage

vehicle (Auto sales)

property (Home sales)

primaryContractHolder

addresses and the address shape

Each address slot (property, mailing, billing) has the same shape. mailing and billing are always required. property is required for Home sales and forbidden for Auto sales.

paymentPlan

paymentInstrument

Provide card for Card payments, bank for ACH, neither for Invoice. Providing both, or the wrong one, is rejected.

Card security codes (CVV) are not collected and are not part of the request.

Enumerations

Response objects

Error / warning item

Error Handling & Code Catalog

Validation order

A sale is checked in stages. Format and structure are checked first; if they fail, the later stages do not run. Within a stage, all violations are collected and returned together.

Errors vs warnings

• Errors reject the sale (or batch row). Fix the input and resubmit.
• Warnings do not block booking; they ride along in the warnings array. Only 60101 (SALE_DATE_STALE) is currently emitted; 60102 (ADDRESS_UNVERIFIED) is reserved for a future release.

Full code catalog

HTTP status is 422 unless noted. Search by number, name, field, or message; filter by stage. Links elsewhere in this guide jump straight to a code below.

Non-Functional Requirements

Performance & timeouts

• All calls are synchronous; the response is returned when processing completes.
• Request bodies are capped at 1 MB; a larger request is rejected with HTTP 413 before any processing.
• Date rules (sale date not in the future, 30-day backdate limit, 90-day stale warning) are judged on the US Central business clock, not UTC.

Pagination

Not applicable. The API has no list/collection (GET) endpoints in v1; all operations are submissions.

Idempotency & duplicate handling

• There is no client-supplied idempotency key in v1.
• Duplicate protection is server-side via the globally unique contractNumber (across all administrators). A repeat submission is rejected with 50008.
• Retry guidance: on 502 or 503, no sale was booked — retry with backoff. On 500: 60303 and 60305 are safe to resubmit; with 60304, do not blindly retry — contact Arch. On 422 with 60306 or 60307, the producer's payment configuration is incomplete — contact Arch before retrying. For batches, a 200 with some rejected rows means only the rejected rows need correcting; do not resend accepted rows.

Webhooks / callbacks

None in v1. The API does not call back to partner systems; all results are returned in the synchronous response.

Security & compliance

• Transport: HTTPS only; minimum TLS 1.2; HTTP/2 enabled.
• Gateway: Azure API Management; an Ocp-Apim-Subscription-Key header is required on every request (sandbox and production).
• Authentication: OAuth 2.0 client credentials; HS256-signed JWT bearer tokens; 30-minute lifetime. Client secrets stored as salted PBKDF2-SHA256 hashes.
• Card data (PCI): card numbers are passed through to Arch's payment processor and tokenized (vaulted); ArchPay does not persist raw card numbers. CVV is not collected. Integrators must still handle card data in a PCI-compliant manner on their side.
• Data residency: United States.

Implementation Notes & Assumptions

Key design decisions and behaviors worth knowing when building against the API.

Assumptions & design decisions worth knowing

• contractNumber is normalized (uppercased, spaces removed) before duplicate checking, and is globally unique across all administrators.
• All independent validation problems are returned together in one response (not fail-fast within a stage).
• Catalog message text is canonical; runtime messages may be slightly more specific (e.g. producer 3999 is not known, or a duplicate citing the existing contractId).
• Every API response carries a requestId correlation id — including 401, 413, and 503. Gateway responses (missing/invalid subscription key 401, rate-limit 429) do not.
• Auth failures return {"status":"rejected","requestId":"...","error":"invalid_token"} with header WWW-Authenticate: Bearer.
• The token endpoint returns OAuth-style {"error":...} for credential/availability problems but the coded envelope for a missing form field.