Persons

Persons describe contacts that may be referenced in other entities. Person entities contain the source of truth for information such as name, contact methods, and profile pictures. On this page, we'll dive into the different person endpoints you can use to manage contacts programmatically.

The person model

The person model contains all the information about your contacts, including their name, email, and custom fields.

Properties

Name
personId
Type
string
Description
Unique identifier for the person.
Name
firstName
Type
string
Description
The person's first name.
Name
lastName
Type
string
Description
The person's last name.
Name
email
Type
string
Description
The person's email address.
Name
phone
Type
string | null
Description
The person's preferred phone number, or else the phone number added to the contact first. Phone and SMS-only numbers both count. It is returned as stored, so it may not be in E.164 format (+14155550123). null when the person has no phone number.
Name
smsConsent
Type
object | null
Description
Whether the person agreed to receive text messages from your organization at phone. null when the person has no phone number, or when Gatsby couldn't load consent for this request. Treat null as unknown, not as opted out, and never as permission to text. The fields are described below.
Name
profilePicture
Type
string
Description
The URL for the person's profile picture.
Name
company
Type
string
Description
The person's company name.
Name
position
Type
string
Description
The person's job title or position.
Name
birthday
Type
string
Description
The person's birthday.
Name
address
Type
string
Description
The person's street address.
Name
apartment
Type
string
Description
The person's apartment or unit number.
Name
city
Type
string
Description
The person's city.
Name
state
Type
string
Description
The person's state or province.
Name
country
Type
string
Description
The person's country.
Name
postalCode
Type
string
Description
The person's postal or ZIP code.
Name
customFields
Type
object
Description
⚠️ Deprecated: Use customFieldsDetailed instead. This field returns a simple key-value object but lacks field type information and metadata needed for proper updates.
Name
customFieldsDetailed
Type
array
Description
Enhanced custom fields array with full metadata. Each field includes fieldId, fieldName, fieldType (text | multiselect | number), value (string or array for multiselect), and options (for multiselect fields).
Name
eventHistory
Type
array
Description
An array of event objects that the person has been associated with.
Name
contactMethodGroups
Type
array
Description
The person's contact method groups. Each group is a named set of email recipients split into To and CC. Always present, and [] when the person has no groups. The default group comes first, then the rest in the order they were created. The group and recipient fields are described below.

Contact method groups

A contact method group is a named set of email recipients for a person, such as their assistants. When Gatsby emails the person, it uses the default group. The to recipients receive the email and the cc recipients are copied. Recipients are not labeled by role, so only To and CC membership carries meaning.

Contact method groups are read-only through the REST API. Manage them in the Gatsby dashboard. PUT /person/:id does not change them.

Name
contactMethodGroupId
Type
string
Description
Unique identifier for the group.
Name
name
Type
string
Description
The group's name.
Name
isDefault
Type
boolean
Description
Whether this is the person's default group, the one Gatsby uses when emailing them.
Name
to
Type
array
Description
Recipients who receive the email. May be empty.
Name
cc
Type
array
Description
Recipients who are copied on the email. May be empty.

Each recipient in to and cc has these fields:

Name
contactMethodId
Type
string
Description
Stable identifier for this email address on the person.
Name
name
Type
string
Description
The recipient's display name. May be empty.
Name
email
Type
string
Description
The recipient's email address.

SMS consent

smsConsent describes the consent for the number in phone, for your organization. It matches the SMS consent column on the guest list and in its CSV export. A person with a phone number but no consent recorded has { "consent": "none", "source": null }. Consent is matched whether the number is stored formatted, such as (415) 555-0123, or in E.164, such as +14155550123.

SMS consent is read-only through the REST API.

Name
consent
Type
string
Description
One of optedIn, optedOut, or none.
- optedIn - The person opted in to texts from your organization, or your organization has texted the number and the person has not opted out.
- optedOut - The person opted out of texts from your organization, or replied STOP, which opts the number out of texts from every organization on Gatsby.
- none - No consent is recorded for the number.
Name
source
Type
string | null
Description
How the consent was recorded. null when no source is recorded, such as for an opt-in that comes from your organization having texted the number, or for none.
- stop_keyword - The person replied STOP.
- start_keyword - The person replied START to opt back in.
- block_keyword - The person replied BLOCK to stop texts from your organization.
- preference_center - The person changed their SMS preference on Gatsby's preference page.
- send_error - A text to the number failed because the number had opted out.
- manual - Gatsby support set the consent.
- import - The consent came from a contact import.
- survey_opt_in - The person opted in through an SMS opt-in question on an RSVP form.

GET/person

List all persons

This endpoint allows you to retrieve a paginated list of all persons in your organization. By default, a maximum of 50 persons are returned.

Optional attributes

Name
limit
Type
integer
Description
Maximum number of persons to return. Defaults to 50.
Name
skip
Type
integer
Description
Number of persons to skip for pagination. Defaults to 0.

Request

GET

/person

curl -G https://rest.gatsby.events/person \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}"

Response

{
  "persons": [
    {
      "personId": "52907745-7672-470e-a",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+14155550123",
      "smsConsent": {
        "consent": "optedIn",
        "source": "survey_opt_in"
      },
      "profilePicture": "https://assets.gatsby.events/avatars/johndoe.jpg",
      "address": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "customFields": {
        "title": "Software Engineer",
        "company": "Acme Inc"
      },
      "contactMethodGroups": [
        {
          "contactMethodGroupId": "6f1c2a9e-3b7d-4f0a-9c51-2d8e7a4b1c90",
          "name": "Executive assistants",
          "isDefault": true,
          "to": [
            {
              "contactMethodId": "a3e15b7c-9d24-4f61-8e0a-1c2b3d4e5f60",
              "name": "Jordan Lee",
              "email": "[email protected]"
            }
          ],
          "cc": [
            {
              "contactMethodId": "b7c26d8e-0f35-4a72-9b1c-2d3e4f5a6b71",
              "name": "Sam Rivera",
              "email": "[email protected]"
            },
            {
              "contactMethodId": "c9d47e9f-1a46-4b83-8c2d-3e4f5a6b7c82",
              "name": "Alex Kim",
              "email": "[email protected]"
            }
          ]
        }
      ]
    },
    {
      "personId": "8293b8f2-3019-42a8-b"
      // ...
    }
  ]
}

POST/person

Create a person

This endpoint allows you to create a new person in your organization. The API will check if a person with the provided email already exists. If a duplicate email is found, a 409 Conflict error will be returned.

Required attributes

Name
firstName
Type
string
Description
The person's first name.
Name
lastName
Type
string
Description
The person's last name.
Name
email
Type
string
Description
The person's email address. Must be unique among non-archived persons.

Optional attributes

Name
company
Type
string
Description
The person's company name.
Name
position
Type
string
Description
The person's job title or position.
Name
phone
Type
string
Description
The person's phone number.
Name
birthday
Type
string
Description
The person's birthday.
Name
address
Type
string
Description
The person's street address.
Name
apartment
Type
string
Description
The person's apartment or unit number.
Name
city
Type
string
Description
The person's city.
Name
state
Type
string
Description
The person's state or province.
Name
country
Type
string
Description
The person's country.
Name
postalCode
Type
string
Description
The person's postal or ZIP code.
Name
contextNote
Type
string
Description
Notes or context about the person.

Request

POST

/person

curl https://rest.gatsby.events/person \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}" \
  -d '{"firstName":"John","lastName":"Doe","email":"[email protected]"}'

Response

{
  "personId": "52907745-7672-470e-a"
}

GET/person/:id

Retrieve a person

This endpoint allows you to retrieve a person by providing their personId. This includes detailed information about the person, including their event history.

Request

GET

/person/52907745-7672-470e-a

curl https://rest.gatsby.events/person/52907745-7672-470e-a \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}"

Response

{
  "personId": "52907745-7672-470e-a",
  "firstName": "John",
  "lastName": "Doe",
  "email": "[email protected]",
  "phone": "+14155550123",
  "smsConsent": {
    "consent": "optedIn",
    "source": "survey_opt_in"
  },
  "profilePicture": "https://assets.gatsby.events/avatars/johndoe.jpg",
  "address": "123 Main St",
  "city": "San Francisco",
  "state": "CA",
  "customFields": {
    "Title": "Software Engineer",
    "Company": "Acme Inc",
    "Tags": "VIP"
  },
  "customFieldsDetailed": [
    {
      "fieldId": "field-123",
      "fieldName": "Title",
      "fieldType": "text",
      "value": "Software Engineer",
      "valueId": "value-456"
    },
    {
      "fieldId": "field-789",
      "fieldName": "Company",
      "fieldType": "text",
      "value": "Acme Inc",
      "valueId": "value-012"
    },
    {
      "fieldId": "field-345",
      "fieldName": "Tags",
      "fieldType": "multiselect",
      "value": ["VIP", "Board Member"],
      "valueId": "value-678",
      "options": [
        { "id": "opt-1", "value": "VIP", "color": "#FFD700" },
        { "id": "opt-2", "value": "Board Member", "color": "#4169E1" },
        { "id": "opt-3", "value": "Sponsor", "color": "#32CD32" }
      ]
    }
  ],
  "eventHistory": [
    {
      "eventId": "e8dj2ns9-34kd-9j3b",
      "name": "Annual Conference 2023",
      "slug": "annual-conference-2023",
      "date": "2023-11-15T09:00:00Z",
      "rsvpStatus": "Accepted",
      "rsvpStatusHistory": [
        {
          "status": "Invited",
          "actorId": "admin-user-1",
          "actorType": "user",
          "createdAt": "2023-10-01T14:30:00Z"
        },
        {
          "status": "Accepted",
          "actorId": "52907745-7672-470e-a",
          "actorType": "eventPerson",
          "createdAt": "2023-10-05T10:15:00Z"
        }
      ],
      "attendance": "Attended"
    }
  ],
  "contactMethodGroups": [
    {
      "contactMethodGroupId": "6f1c2a9e-3b7d-4f0a-9c51-2d8e7a4b1c90",
      "name": "Executive assistants",
      "isDefault": true,
      "to": [
        {
          "contactMethodId": "a3e15b7c-9d24-4f61-8e0a-1c2b3d4e5f60",
          "name": "Jordan Lee",
          "email": "[email protected]"
        }
      ],
      "cc": [
        {
          "contactMethodId": "b7c26d8e-0f35-4a72-9b1c-2d3e4f5a6b71",
          "name": "Sam Rivera",
          "email": "[email protected]"
        },
        {
          "contactMethodId": "c9d47e9f-1a46-4b83-8c2d-3e4f5a6b7c82",
          "name": "Alex Kim",
          "email": "[email protected]"
        }
      ]
    }
  ]
}

GET/person/search

Search persons

This endpoint allows you to search for persons in your organization by name or email. You must provide either query OR email (not both).

Required attributes (one of)

Name
query
Type
string
Description
Search by person's name. Searches across name, firstName, and lastName fields. Mutually exclusive with email.
Name
email
Type
string
Description
Search by exact email address. Returns all persons with matching email. Mutually exclusive with query.

Optional attributes

Name
includeArchived
Type
boolean
Description
Include archived persons in search results. Defaults to false. Set to 'true' or '1' to include archived persons.
Name
limit
Type
integer
Description
Maximum number of results to return. Defaults to 50.
Name
skip
Type
integer
Description
Number of results to skip for pagination. Defaults to 0.

Request

GET

/person/search

curl -G https://rest.gatsby.events/person/search \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}" \
  -d "query=john" \
  -d "limit=10" \
  -d "skip=0"

Response

{
  "persons": [
    {
      "personId": "52907745-7672-470e-a",
      "firstName": "John",
      "lastName": "Doe",
      "email": "[email protected]",
      "phone": "+14155550123",
      "smsConsent": {
        "consent": "optedIn",
        "source": "survey_opt_in"
      },
      "profilePicture": "https://assets.gatsby.events/avatars/johndoe.jpg",
      "address": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "customFields": {
        "title": "Software Engineer",
        "company": "Acme Inc"
      },
      "contactMethodGroups": [
        {
          "contactMethodGroupId": "6f1c2a9e-3b7d-4f0a-9c51-2d8e7a4b1c90",
          "name": "Executive assistants",
          "isDefault": true,
          "to": [
            {
              "contactMethodId": "a3e15b7c-9d24-4f61-8e0a-1c2b3d4e5f60",
              "name": "Jordan Lee",
              "email": "[email protected]"
            }
          ],
          "cc": [
            {
              "contactMethodId": "b7c26d8e-0f35-4a72-9b1c-2d3e4f5a6b71",
              "name": "Sam Rivera",
              "email": "[email protected]"
            },
            {
              "contactMethodId": "c9d47e9f-1a46-4b83-8c2d-3e4f5a6b7c82",
              "name": "Alex Kim",
              "email": "[email protected]"
            }
          ]
        }
      ]
    },
    {
      "personId": "a9b2c3d4-5e6f-7g8h-9i0j",
      "firstName": "John",
      "lastName": "Smith",
      "email": "[email protected]",
      "phone": "+13105550188",
      "smsConsent": {
        "consent": "optedOut",
        "source": "stop_keyword"
      },
      "profilePicture": "https://assets.gatsby.events/avatars/johnsmith.jpg",
      "address": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "customFields": {
        "title": "Product Manager",
        "company": "Tech Corp"
      },
      "contactMethodGroups": []
    }
  ],
  "total": 2,
  "limit": 5,
  "skip": 0
}

PUT/person/:id

Update a person

This endpoint allows you to update a person's information by providing their personId.

Required attributes

Name
personId
Type
string
Description
The unique identifier for the person.

Optional attributes

Name
firstName
Type
string
Description
The person's first name.
Name
lastName
Type
string
Description
The person's last name.
Name
email
Type
string
Description
The person's email address.
Name
phoneNumber
Type
string
Description
The person's phone number.
Name
company
Type
string
Description
The person's company name.
Name
position
Type
string
Description
The person's job title or position.
Name
birthday
Type
string
Description
The person's birthday.
Name
address
Type
string
Description
The person's street address.
Name
apartment
Type
string
Description
The person's apartment or unit number.
Name
city
Type
string
Description
The person's city.
Name
state
Type
string
Description
The person's state or province.
Name
country
Type
string
Description
The person's country.
Name
postalCode
Type
string
Description
The person's postal or ZIP code.
Name
customFields
Type
array or object
Description
Updates for text and number fields. Each field has a single value. Values can be strings or numbers. Supports two formats:
Array format (preferred): Each object contains fieldId or fieldName, plus value.
[ { "fieldName": "Title", "value": "Engineer" }, { "fieldName": "Salary", "value": 100000 } ]
Object format (legacy): Simple key-value pairs, automatically converted to array format.
{ "Title": "Engineer", "Company": "Acme" }
Name
customFieldMultiselect
Type
array
Description
Updates for multiselect fields. Allows multiple values for the same field. Each object needs fieldId and value.
[ { "fieldId": "field-456", "value": "VIP" }, { "fieldId": "field-456", "value": "Board Member" }, { "fieldId": "field-456", "value": "Donor" } ]
Note: Use customFieldsDetailed from GET responses to identify which fields are multiselect (where fieldType: "multiselect"). Multiselect updates require the fieldId.

Request

PUT

/person/52907745-7672-470e-a

curl -X PUT https://rest.gatsby.events/person/52907745-7672-470e-a \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}" \
  -d '{"personId":"52907745-7672-470e-a","firstName":"John","lastName":"Smith","customFields":[{"fieldName":"Title","value":"Senior Engineer"}],"customFieldMultiselect":[{"fieldId":"field-456","value":"VIP"},{"fieldId":"field-456","value":"Board Member"}]}'

Response

{
  "success": true
}

PUT/persons

Update many persons

This endpoint updates up to 100 persons in one request. Use it instead of calling PUT /person/:id once per contact: a sync of 2,600 contacts takes 26 requests instead of 2,600. Bulk requests have their own rate limit of 20 per minute, with bursts of up to 5.

Each person is updated on its own, so one that fails or does not exist does not stop the rest. The response lists a result for every person, in the order you sent them. Check success on each result rather than relying on the status code alone.

Required attributes

Name
persons
Type
array
Description
Between 1 and 100 person updates. Each entry takes the same fields as Update a person, including both customFields formats, and must include the personId to update. Each personId can appear only once per request.

Response

Name
results
Type
array
Description
One result per entry in persons, in the same order. Each has personId and success. When success is false, error says why, for example Person ID does not exist.

Errors

The whole request fails with 422 Unprocessable Entity only when the body itself is invalid: persons is missing or empty, has more than 100 entries, has an entry without a personId, or repeats a personId. Nothing is updated in that case. The request body can be up to 1 MB.

If the whole request fails on our side you get a 500. Some contacts may already have been updated, and sending the same request again is safe.

Request

PUT

/persons

curl -X PUT https://rest.gatsby.events/persons \
  -H "Authorization: Bearer {token}" \
  -H "organizationSlug: {organizationSlug}" \
  -H "Content-Type: application/json" \
  -d '{"persons":[{"personId":"52907745-7672-470e-a","firstName":"John","customFields":[{"fieldName":"Tier","value":"Gold"}]},{"personId":"8293b8f2-3019-42a8-b","customFields":[{"fieldName":"Tier","value":"Silver"}]}]}'

Response

{
  "results": [
    { "personId": "52907745-7672-470e-a", "success": true },
    {
      "personId": "8293b8f2-3019-42a8-b",
      "success": false,
      "error": "Person ID does not exist"
    }
  ]
}