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
address
Type
string
Description
The person's address.
Name
city
Type
string
Description
The person's city.
Name
state
Type
string
Description
The person's state.
Name
customFields
Type
object
Description
An object containing custom fields for the person.
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 ten persons are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of persons returned.
Name
skip
Type
integer
Description
Number of persons to skip for pagination.

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.

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.

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"
  },
  "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/search

Search persons

This endpoint allows you to search for persons in your organization based on name or email. This is useful for finding specific contacts or filtering persons based on attributes.

Optional attributes

Name
query
Type
string
Description
Search query to match against person's name, email, or other fields.
Name
firstName
Type
string
Description
Filter by person's first name.
Name
lastName
Type
string
Description
Filter by person's last name.
Name
email
Type
string
Description
Filter by person's email address.
Name
city
Type
string
Description
Filter by person's city.
Name
state
Type
string
Description
Filter by person's state.
Name
limit
Type
integer
Description
Limit the number of persons returned.
Name
skip
Type
integer
Description
Number of persons to skip for pagination.

Request

GET

/search

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

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
customFields
Type
object
Description
An object containing custom fields for the person.

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"}'

Response

{
  "success": true
}