Responses and status codes

Understand the MasterID JSON response envelope, the difference between request IDs and session IDs, and how to handle pending and unauthenticated responses.

MasterID returns a consistent JSON envelope for every API call. Learn the difference between the request ID, the session ID, and the collection reference so you route results correctly in your integration.

Success envelope

A completed request returns HTTP 200 with a JSON object containing id and data.

id · string

The API request ID. Every response, including errors, includes this value.

data · object

The operation payload. Its shape depends on the endpoint.

Example: wallet balance

{
  "id": "<REQUEST_ID>",
  "data": {
    "currency": "UGX",
    "balance": 50000
  }
}

Error envelope

An error response returns { id?, error }. The id field is present when MasterID generated a request ID before detecting the failure.

{
  "id": "<REQUEST_ID>",
  "error": "Invalid input"
}

For per-code troubleshooting, see Errors.

Pending response (202)

Operations that finish asynchronously return HTTP 202. The envelope still contains id and data, but the data indicates the operation is processing.

• Verification submissions return a sessionId and a pending status.
• Collection requests return a reference and a pending status.

Store the returned identifier (session ID or reference) and poll or wait for the webhook. Do not submit the same request again with a different key.

Request ID vs session ID vs collection reference

Identifier	Source	Purpose
Request ID	Every API response	Ties a single HTTP call to API history and logs
Session ID	POST /verifications response	Identifies a verification check; use it with GET /verifications/{sessionId}
Collection reference	POST /collections response	Identifies a payment request; use it with GET /collections/{reference}

The request ID and the session ID are different values. Store the session ID or collection reference so you can retrieve final results later.

Unauthenticated browser visits

If you open an API URL in a browser without credentials, MasterID returns service information only. No workspace data, balance, or records are exposed.

Response-handling helper

Use a small helper to normalise every response and extract the request ID for logging.

response-handler.ts

const BASE_URL = "https://masterid.me/api/public/v1";

async function callMasterID(path: string, init?: RequestInit) {
  const res = await fetch(`${BASE_URL}${path}`, {
    ...init,
    headers: {
      "X-API-Key": process.env.MASTERID_API_KEY!,
      "X-API-Secret": process.env.MASTERID_API_SECRET!,
      "Content-Type": "application/json",
      ...init?.headers,
    },
  });

  const body = await res.json().catch(() => ({}));

  if (!res.ok) {
    const err: any = new Error(body.error || `HTTP ${res.status}`);
    err.status = res.status;
    err.requestId = body.id ?? null;
    throw err;
  }

  return {
    requestId: body.id,
    data: body.data,
    status: res.status,
  };
}

// Usage
const { requestId, data } = await callMasterID("/wallet");
console.log("request", requestId, "balance", data.balance);

Always log the request ID. It makes support requests faster when you need to trace a specific call.