API reference

Inspect the integration

Read who the key belongs to, the integration's state, any open sync, and the limits.

Request

GEThttps://www.postaged.com/api/integrations/push/v1

Who the key belongs to, the integration's state, any open sync, and the limits.

curl https://www.postaged.com/api/integrations/push/v1 \
  -H "Authorization: Bearer $POSTAGED_API_KEY"

const response = await fetch("https://www.postaged.com/api/integrations/push/v1", {
  headers: {
    Authorization: `Bearer ${process.env.POSTAGED_API_KEY}`,
  },
});
const result = await response.json();
console.log(result);

import os

import requests

response = requests.get(
    "https://www.postaged.com/api/integrations/push/v1",
    headers={"Authorization": f"Bearer {os.environ['POSTAGED_API_KEY']}"},
    timeout=60,
)
print(response.json())

Authentication

An integration key (it starts with pk_int_), created with New key on the integration's page. Send it in the Authorization: Bearer header. Only that integration's key works here; any other key gets 401 invalid_key.

Headers

Authorization: Bearer $POSTAGED_API_KEY
Content-Type: application/json

Response 200

The integration.

integrationobject
- idstring
  The integration's public id.
- namestring
- statusstring
  The integration's state, for example setup_needed, ready, or syncing.
- setupCompleteboolean
openSyncnull or object
- idstring
- modestring
  One of full or delta.
- expiresAtstring
- batchesReceivedinteger
limitsobject
- recordsPerBatchinteger
  Always 1000.
- bytesPerBatchinteger
  Always 4456448.
- declaredFieldsinteger
  Always 1000.
- syncExpiryHoursinteger
  Always 24.
nextStepstring

Response200 OK

{
  "integration": {
    "id": "int_ABCD1234",
    "name": "Dandy CRM",
    "status": "setup_needed",
    "setupComplete": false
  },
  "openSync": null,
  "limits": {
    "recordsPerBatch": 1000,
    "bytesPerBatch": 4456448,
    "declaredFields": 1000,
    "syncExpiryHours": 24
  },
  "nextStep": "Push a first sync, then finish setup in Postaged to choose which fields to keep."
}

Errors

Errors use the body { "error": { "code", "message", "details" } }; details appears only on some codes. Full tables: Error reference.

Status	code	message	What to do
401	`invalid_key`	That API key is not valid for this integration.	Send this integration's key (it starts with pk_int_) in the Authorization: Bearer header. A revoked key, another kind of key, or a key for a removed integration gets this error.
403	`integration_unavailable`	This integration is not accepting data. Contact support if you think that is wrong.	The integration is paused or disconnected in Postaged. Ask the owner to resume it, then send the request again.
429	`rate_limited`	Too many requests. Slow down and retry.	Wait the number of seconds in the Retry-After header, then send the request again.

invalid_key401

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer realm="Postaged"

{
  "error": {
    "code": "invalid_key",
    "message": "That API key is not valid for this integration."
  }
}

integration_unavailable403

{
  "error": {
    "code": "integration_unavailable",
    "message": "This integration is not accepting data. Contact support if you think that is wrong."
  }
}

rate_limited429

HTTP/1.1 429 Too Many Requests
Retry-After: 60

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests. Slow down and retry."
  }
}