Replace the mailing list
Contacts API

PUThttps://www.prayerletters.com/api/v1/contacts

Remove all current contacts and upload a new mailing list.

The body of the request should be formatted identically to the response from the GET call.

When you include a non-null external_id field with a record, the response will contain a mapping between your ID and the contact_id at prayerletters.com. You can then use the contact_id to update or delete the record as needed.

Scope Required

contacts.write

Request Body

contacts.v1 Object

Example

{
   "contacts" : [
      {
         "address" : {
            "city" : "Lebanon",
            "country" : "",
            "postal_code" : "03766",
            "state" : "NH",
            "street" : "123 Main St."
         },
         "company" : null,
         "contact_id" : "c-###-####",
         "external_id" : null,
         "file_as" : "Tischler, Joe",
         "greeting" : "Joe and Mary",
         "name" : "Joe and Mary Tischler"
      },
      {
         "address" : {
            "city" : "Lebanon",
            "country" : "",
            "postal_code" : "03766",
            "state" : "NH",
            "street" : "123 Main St."
         },
         "company" : null,
         "contact_id" : "c-###-####",
         "external_id" : null,
         "file_as" : "Tischler, Joe",
         "greeting" : "Joe and Mary",
         "name" : "Joe and Mary Tischler"
      }
   ]
}

Response

200 OK

Response Body

contacts.contacts_created.v1 Object

Example

{
   "contacts" : [
      {
         "contact_id" : "c-###-####",
         "external_id" : "..."
      },
      {
         "contact_id" : "c-###-####",
         "external_id" : "..."
      }
   ]
}

Rate Limit

  • 4 requests per hour
  • 12 requests per day

This endpoint has a low limit because it should only be used when doing an initial mailing list sync or when troubleshooting bugs. Use the single-contact add/update/delete endpoints for normal mailing list updates.

Errors

500 contacts.error_creating_record

There was a database error on our end.

Important: the mailing list may now be in an inconsistent state. We recommend sending a Delete all contacts request, then sending this PUT request again. If you get the same error, delete all contacts again to ensure that a mailing isn't submitted to a partially-uploaded list, and contact us for assistance.

As a workaround, give the user of your application a copy of the mailing list in another format (e.g. CSV or Excel), and ask them to send it to us with their mailing (either through our web site or by email). We will be able to import the list and continue with any active orders once the database error has been resolved.

423 contacts.locked

Another API call is already in the process of replacing contacts on this account.

429 contacts.too_many_requests

Database-intensive queries have lower thresholds for throttling. Contact us if you need higher limits for testing purposes on a particular access token.

400 contacts.upload_body_missing

The request did not contain any content.

400 contacts.upload_insufficient_address

At least one contact does not appear to have a mailing address (at least one of street or city must be filled in).

400 contacts.upload_invalid_address

At least one contact has an address attribute that isn't a JSON object.

412 contacts.upload_invalid_contacts_attribute

The contacts attribute must be an array.

412 contacts.upload_invalid_content

The content must be a JSON object.

412 contacts.upload_invalid_format

The content must follow the JSON format.

400 contacts.upload_missing_address

At least one contact is missing an address attribute.

412 contacts.upload_missing_contacts_attribute

The content must contain a contacts array.

400 contacts.upload_missing_name

At least one contact is missing a name or company.

413 contacts.upload_too_large

By default, uploads may not exceed 2MB. If you need a larger limit, please contact us.

API Overview
Contacts API
Files API
Hooks API
Orders API