Authenticating and making your first API call

Prerequisites

Before making your first call you need three things: a sandbox account, an API key, a tenant ID, and a client secret.

• Sandbox account. Register at the MOS developer portal. Your account is provisioned to a sandbox tenant with no production data.
• API key. After registration, navigate to Settings → API Keys in the portal. Generate a new key and copy it immediately. It is shown in full only once.
• Tenant ID. Your tenant ID appears on the same Settings page, labeled Tenant ID. It is a UUID string and does not change.
• Client secret. The client secret is provisioned when your access request is approved by the MOS support organization. You will receive an email with a 1Password link containing the client secret. Store it securely alongside your API key. If you have not received this email, contact your MOS integration team before proceeding.

Every request to the MOS API must carry all three credentials as HTTP headers. There is no OAuth flow for system integrations; the headers are the only authentication mechanism required.

Authentication

The API requires three headers on every request:

• x-api-key — your API key
• x-tyk-mos-client-secret — your client secret, provisioned at tenant approval and delivered via 1Password
• tenant-id — your tenant ID

There is no token exchange, no session, and no expiry on the key or client secret themselves. All three headers are required on every call. A request missing any of them will return 401 Unauthorized.

The single unauthenticated endpoint is GET /health, which returns the API's operational status. All other endpoints require the full header set.

If you are building a backend integration, store all three values as environment variables and inject them at request time. Do not embed them in client-side code or commit them to source control.

Your first request

The entry point for every loan integration is POST /loans. This creates a loan record that anchors all documents, extracted data, and analytics events for that loan. The only required field in the request body is externalLoanId, which is your LOS loan number used to map MOS records back to your system.

curl -X POST https://api.mos.true.ai/v1/loans \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-tyk-mos-client-secret: YOUR_CLIENT_SECRET" \
  -H "tenant-id: YOUR_TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{"externalLoanId": "your-los-loan-number"}'

Replace the placeholder values with your actual credentials. The externalLoanId value should match whatever identifier your LOS uses for this loan: a loan number, a GUID, or any string up to 255 characters.

A successful call returns HTTP 201 Created with a JSON body.

Reading the response

The POST /loans response contains the loan record as created. The field you need immediately is loanId:

{
  "loanId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "externalLoanId": "your-los-loan-number",
  "status": "Active",
  "createdAt": "2026-06-09T14:32:00Z"
}

loanId is the MOS-generated UUID for this loan. It is the path parameter you pass to every subsequent call in the loan lifecycle: document uploads, document listing, extracted data retrieval, income clarity, and analytics. Store it alongside your external loan identifier in whatever database or cache your integration uses.

The status field begins as Active. Valid loan statuses are Active, Pending, Closed, and Cancelled. Status does not affect which endpoints are callable. It is informational and used for reporting purposes.

Error shapes

All error responses from the MOS API follow a consistent three-field structure:

{
  "status": 400,
  "message": "externalLoanId is required",
  "error": "Bad Request"
}

The status codes you will encounter most often:

• 400 Bad Request. The request body is missing a required field or contains an invalid value. The message field identifies the specific problem.
• 401 Unauthorized. One or more required authentication headers are missing, malformed, or do not match valid credentials for the given tenant.
• 403 Forbidden. The credentials are valid but do not have permission to access the requested resource.
• 404 Not Found. The loanId, documentId, or other path parameter does not exist in your tenant's data.

Always check the message field first when debugging. The error field maps to the HTTP spec; message is where the actionable detail lives.

Next steps

With a loanId in hand, the next step is uploading documents and running the Loan Setup pipeline. The Loan Setup workflow handles automatic classification, field extraction, and data validation for every document you upload. See the Building the Loan Setup integration guide for the complete upload-to-extraction flow.

If you are building the income analysis step, review the Setting up Income Clarity guide, which requires Loan Setup to complete first.