Response envelope

Every JSON response from the Poptin API - success or failure - follows the same top-level envelope. Parse it once in your client and every operation becomes predictable: check one boolean, then read the payload from a known field.

The envelope is returned by operations served under https://api.popt.in/v1 and authenticated with a pk_live_ bearer key.

Fields

Field	Type	Description
`success`	boolean	`true` if the request succeeded, `false` otherwise. Use this as your primary branch.
`message`	string	Human-readable summary of the outcome. Safe for logs; not intended as UI copy.
`data`	object \| null	Response payload on success. `null` on error responses.
`errors`	object \| array \| null	Error details on failure - typically a map of field → messages for validation errors. `null` on success.
`meta`	object \| null	Pagination metadata for list endpoints. Its fields depend on whether the operation uses cursor or offset pagination. `null` when not applicable.

success is authoritative. Do not rely on the presence of data or errors alone to infer status - always branch on success first.

Success example

A successful response returns success: true, a data payload, and null for errors. On non-list endpoints, meta is typically null.

{
  "success": true,
  "message": "Request completed successfully.",
  "data": { },
  "errors": null,
  "meta": null
}

The shape of data varies by operation - a single object for show endpoints, an array for list endpoints, or an empty object when there is no payload to return. See the individual operation page in the API Reference for the exact schema.

List response metadata

List endpoints return a populated meta object, but there are two supported shapes:

List contacts and List conversions use cursor pagination with per_page, next_cursor, prev_cursor, and has_more. They do not return totals or page numbers.
Other list endpoints use offset pagination with current_page, last_page, per_page, and total.

See Pagination for request examples and iteration guidance.

Error example

Failed responses return success: false, a null data, and populated errors. HTTP 422 (validation) is the most common case where errors maps field names to human-readable messages:

{
  "success": false,
  "message": "The given data was invalid.",
  "data": null,
  "errors": {
    "value": ["The value is required."]
  },
  "meta": null
}

Other failure modes (401, 403, 404, 409, 422, 423, 429) use the same envelope. The HTTP status code identifies the class of error; errors and message describe the specifics.

How to parse

Follow the same three steps for every response:

Branch on success. If true, read data. If false, read errors and message and surface them to your caller.
For list endpoints, read meta. Cursor fields or page totals live there, depending on the endpoint. See Pagination for the exact fields and how to iterate.
Use the HTTP status code for classification. The envelope tells you what went wrong; the status code tells you how to react (retry, back off, fix input, escalate). See HTTP status codes for the full list.