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

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]",
      "profilePicture": "https://assets.gatsby.events/avatars/johndoe.jpg",
      "address": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "customFields": {
        "title": "Software Engineer",
        "company": "Acme Inc"
      }
    },
    {
      "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]",
  "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"
    }
  ]
}

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]",
      "profilePicture": "https://assets.gatsby.events/avatars/johndoe.jpg",
      "address": "123 Main St",
      "city": "San Francisco",
      "state": "CA",
      "customFields": {
        "title": "Software Engineer",
        "company": "Acme Inc"
      }
    },
    {
      "personId": "a9b2c3d4-5e6f-7g8h-9i0j",
      "firstName": "John",
      "lastName": "Smith",
      "email": "[email protected]",
      "profilePicture": "https://assets.gatsby.events/avatars/johnsmith.jpg",
      "address": "456 Oak Ave",
      "city": "Los Angeles",
      "state": "CA",
      "customFields": {
        "title": "Product Manager",
        "company": "Tech Corp"
      }
    }
  ],
  "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. 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
}