Skip to main content

Get a list of persons​

Retrieve a paged collection of persons (required scope contacts:persons:read)

Query Parameters
    sortBy PersonSortOptions

    Possible values: [surname, createdAt]

    The field to sort items in the page by

    direction SortDirection

    Possible values: [ascending, descending]

    The direction to apply the sort

    contactId int64[]

    Only return persons where contactId matches the value(s) provided

    surname string

    Only return persons where surname matches or starts with the value provided

    email string

    Only return persons where email matches the value provided

    mobile string

    Only return persons where mobile matches the value provided

    landline string

    Only return persons where landline matches the value provided

    isOptedOut boolean

    Only return persons where isOptedOut matches the value provided

    pageNumber int32

    Possible values: >= 1 and <= 2147483

    The page number being requested (minimum: 1, maximum: 2147483)

    pageSize int32

    Possible values: >= 1 and <= 1000

    The page size being requested (minimum: 1, maximum: 1000)

Header Parameters
    Customer-Id int64 required

    The customer identifier

Responses

Success

Schema
    items object[]

    The items returned for the requested page

  • Array [
    • id uuid

    The unique identifier of the person

    createdAt date-time

    The UTC timestamp of when this person was created

    contactId int64

    The unique identifier of the contact that this person belongs to

    title string

    The person's title

    forename string

    The person's first name

    surname string

    The person's second name

    email string

    The email address of the person

    mobile string

    The mobile telephone number of the person

    landline string

    The landline telephone number of the person

    extension string

    The landline extension of the person

    position string

    The job role that the person holds within the contact

    department string

    The department that the person belongs to

    isOptedOut boolean

    A flag indicating if the contact has opted out of marketing communications

    customFields object[]

    Custom fields associated with persons

  • Array [
    • definitionId int64

    The unique identifier of the associated custom field definition

    value string nullable

    The current value set for the custom field

    definition object

    Represents the definition of a custom field

    caption string

    The caption of a custom field

    type CustomFieldType

    Possible values: [boolean, integer, decimal, text, list, statement, date, note, time, systemList]

    The type of the custom field. New field types may be added in the future, so integrations should be resilient to this

    Possible values:

    • boolean: Indicates a boolean field (Example: "false")
    • integer: Indicates an integer numeric field (Example: "1001")
    • decimal: Indicates a floating point numeric field (Example: "1.42")
    • text: Indicates an editable text field (Example: "Purple")
    • list: Indicates a field with a single value from a predefined list of options (Example: "Purple")
    • statement: Indicates a text field that cannot be edited. The value is always equal to the default value (Example: "By signing this you agree to the following...")
    • date: Indicates a date field, which will be represented as an RFC3339 formatted date string. The default value is not supported for this type and will always be null (Example: "2024-01-31")
    • note: Indicates a multiline, editable text field. Lines are seperated with a line feed character (Example: "This is a note.")
    • time: Indicates a time field, formatted as HH:mm. The default value is not supported for this type and will always be null (Example: "10:30")
    • systemList: Indicates the ID of a related resource, vehicle or web user (Example: "228007")

    listOptions string[] nullable

    Shows the possible values for a list type custom field. Value will be null if type is not list

    isRequired boolean

    Indicates if the field is required in the UI. This is NOT enforced in the API

    isEditable boolean

    Indicates if the field is editable

    default string nullable

    The default value of a custom field. Formatted in accordance with the rules of the field type

    systemListValueMetadata object

    Represents details of custom field value of type system list

    label string nullable

    A descriptive label for the specific resource, vehicle or web user that this system list value relates to

    entityType CustomFieldSystemListType

    Possible values: [resource, vehicle, webUser]

    The type of entity used for custom field value of type system list

    Possible values:

    • resource
    • vehicle
    • webUser

  • ]
  • ]
    • pageNumber int32

    The page number of the response where 1 is the first page

    pageSize int32

    The number of items requested for the current page

    pageItemCount int32

    The number of items returned in the current page

Loading...