Skip to main content
POST
cURL
Create a contact, or update an existing one with the same email. The response status field (created, updated, or unchanged) tells you which happened, so integrations can branch without a separate lookup. On an existing contact, scalar fields are only filled where they are currently empty — customer-entered values are never overwritten — and tags are attached only when the contact is newly created.

Authorizations

Authorization
string
header
required

HTTP Basic Authentication using API Key and Secret Key. The credentials should be Base64 encoded in the format 'api_key:secret_key'. You can obtain your API Key and Secret Key from Feedspace → Automation → API (https://app.feedspace.io/automation/api).

Body

application/json
email
string<email>
required

Contact email. The upsert key; lowercased and trimmed.

Maximum string length: 255
name
string
Maximum string length: 255
phone
string
Maximum string length: 50
country
string
Maximum string length: 100
state
string
Maximum string length: 100
city
string
Maximum string length: 100
zipcode
string
Maximum string length: 20
company
string
Maximum string length: 255
date_added
string<date>

Date the contact was added (YYYY-MM-DD). Common date formats are accepted and normalised.

external_metadata
object

Arbitrary key/value metadata from your system. Merged per key on update (existing keys are preserved).

tag_ids
integer[]

Tag IDs to attach (must exist in this workspace). Applied only when the contact is newly created.

tags
string[]

Tag names to attach; missing tags are auto-created. Applied only when the contact is newly created.

Maximum string length: 100
primary_source
enum<string>

Override the source stamp. Defaults to public_api for API-key requests. Locked to the first value; never changed on later upserts.

Available options:
csv,
public_api,
review_submission,
manual,
social_import,
stripe

Response

200 - application/json

Contact upserted. Returns 200 when the contact was updated or unchanged, 201 when a new contact was created.

status
enum<string>

Which operation occurred. Use this to branch in integrations.

Available options:
created,
updated,
unchanged
contact
object