API reference

Declare the schema

Declare the fields you will push, with their types and the contact columns they fill.

Request

POSThttps://www.postaged.com/api/integrations/push/v1/schema

Declares the fields you will push. A declaration is a proposal: a field whose type the owner already set in Postaged keeps it, and the call fails with field_locked naming those fields.

curl https://www.postaged.com/api/integrations/push/v1/schema \
  -H "Authorization: Bearer $POSTAGED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": [
      {
        "key": "email",
        "label": "Email",
        "type": "text",
        "semantic": "email"
      },
      {
        "key": "deal_value",
        "label": "Deal value",
        "type": "number"
      }
    ]
  }'

const response = await fetch("https://www.postaged.com/api/integrations/push/v1/schema", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.POSTAGED_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    fields: [
      {
        key: "email",
        label: "Email",
        type: "text",
        semantic: "email",
      },
      {
        key: "deal_value",
        label: "Deal value",
        type: "number",
      },
    ],
  }),
});
const result = await response.json();
console.log(result);

import os

import requests

response = requests.post(
    "https://www.postaged.com/api/integrations/push/v1/schema",
    headers={"Authorization": f"Bearer {os.environ['POSTAGED_API_KEY']}"},
    json={
        "fields": [
            {
                "key": "email",
                "label": "Email",
                "type": "text",
                "semantic": "email",
            },
            {
                "key": "deal_value",
                "label": "Deal value",
                "type": "number",
            },
        ],
    },
    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

Request body

fieldsarray of objectsRequired
Up to 1,000 items.
- keystringRequired
- labelstringOptional
- typestringOptional
  One of text, number, date, yes_no, or choice.
- optionsarray of stringsOptional
  The choices of a choice field.
- semanticstringOptional
  The Postaged contact column this field fills. One of first_name, last_name, address_1, address_2, city, state, zip, email, phone, or organization.

Request body

{
  "fields": [
    {
      "key": "email",
      "label": "Email",
      "type": "text",
      "semantic": "email"
    },
    { "key": "deal_value", "label": "Deal value", "type": "number" }
  ]
}

Response 200

The declaration was applied.

okboolean
Always true.
addedinteger
Fields declared for the first time.
noLongerSentarray of strings
Declared fields this declaration no longer mentions. They keep their columns and values.

Response200 OK

{
  "ok": true,
  "added": 1,
  "noLongerSent": []
}

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
400	`invalid_json`	The request body must be JSON.	Send the body as JSON with a Content-Type of application/json.
400	`invalid_request`	Send { fields: [...] } describing your columns.	Send the body in the shape the message names, then send the request again.
400	`too_many_fields`	You declared 1001 fields. The limit is 1000.	Declare at most the fields in details.limit, counting the fields already declared.
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.
409	`field_locked`	These fields have a type set in Postaged and cannot be changed from here.	The owner set these fields' types in Postaged. Declare them with the types they already have, or ask the owner to change them.
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_json400

{
  "error": {
    "code": "invalid_json",
    "message": "The request body must be JSON."
  }
}

invalid_request400

{
  "error": {
    "code": "invalid_request",
    "message": "Send { fields: [...] } describing your columns."
  }
}

too_many_fields400

{
  "error": {
    "code": "too_many_fields",
    "message": "You declared 1001 fields. The limit is 1000.",
    "details": { "limit": 1000, "received": 1001 }
  }
}

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."
  }
}

field_locked409

{
  "error": {
    "code": "field_locked",
    "message": "These fields have a type set in Postaged and cannot be changed from here.",
    "details": {
      "fields": ["deal_value"]
    }
  }
}

rate_limited429

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

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