Create a new contact

The body of the request should be a json object formatted identically to a contact object in the response from the GET call.

Body Parameters

The contact's company, church, or other organization. It will be printed beneath the name and above the street address.

Leave the country blank if the contact is in the United States.

For non-US addresses, use the English name of the country (e.g. Germany rather than Deutschland). Place other elements of the address in the city, state, and postal_code fields normally.

For example, even though German addresses place the postal code before the city name, keep the city in the city field and the postal code in the postal_code field. Our software automatically reformats international addresses as needed when printing envelopes.

Use this field to store your application's identifier for this contact.

The name we should use when showing this contact in a list. It is usually in the format LastName, FirstName for individuals, or just the regular name for companies and churches.

If the file_as parameter is not included, one will be generated automatically, based on the contact's name.


The name we should use in the first line of a mail-merged letter, usually following the word "Dear".

If the greeting parameter is not included, one will be generated automatically, based on the contact's name.

The contact's full name, as it should appear on the first line of an envelope.
The street address may contain multiple lines

Example Request

{ "contact" : { "address" : { "city" : "Lebanon", "country" : "", "postal_code" : "03766", "state" : "NH", "street" : "123 Main St." }, "company" : null, "external_id" : "0123456", "file_as" : "Tischler, Joe", "greeting" : "Joe and Mary", "name" : "Joe and Mary Tischler" } }

Successful Response

HTTP/1.1 201 Created
{ "contact_id" : "c-3y2-s4at" }

Error Responses

400 contacts.missing_name
The contact must have a name or company.
400 contacts.upload_body_missing
The request did not contain any content
400 contacts.upload_insufficient_address
The 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
The contact contains an address attribute that isn't a JSON object.
400 contacts.upload_missing_address
The one contact is missing an address attribute.
400 contacts.upload_missing_name
The contact is missing a name or company.
412 contacts.upload_invalid_content
The content must be a JSON object.
412 contacts.upload_invalid_format
The content must be a JSON file.
412 contacts.upload_missing_contact_attribute
The JSON file must contain a contact object.
500 contacts.error_creating_record
There was a database error on our end when creating the contact.