List people

List people with aggregated message statistics across all their platform identities

GET/people

Authorization

AuthorizationBearer token · headerrequired

Organization API key (modem_…).

Query parameters

pageinteger

default: 1

limitinteger

max 100 · default: 50

searchstring

min length 1

sortBystring

default: "lastSeen"

Allowed:lastSeenmessageCount

sortOrderstring

default: "desc"

Allowed:ascdesc

ecosystemTagsstring[]

Filter by ecosystem tags (OR match)

companyIdstring

Filter to people currently associated with this company

matches ^\d+$

Responses

200

dataobject[]required

Show properties

Array of object

avatarUrlstring<uri> | nullrequired

Avatar image URL for the person.

Show properties

Any of:

string<uri>

string<uri>

null

null

companyobject | nullrequired

Show properties

Any of:

object

domainstring | nullrequired

Show properties

Any of:

string

string

null

null

idstringrequired

logoUrlstring | nullrequired

Show properties

Any of:

string

string

null

null

namestringrequired

null

null

displayNamestringrequired

Display name for the person.

idstringrequired

matches ^\d+$

identitiesobject[]required

Show properties

Array of object

platformstringrequired

matches ^[a-z0-9]+(?:-[a-z0-9]+)*$

platformIdstringrequired

identityCountintegerrequired

isVipbooleanrequired

lastSeenAtstring<date-time> | null

Show properties

Any of:

string<date-time>

string<date-time>

null

null

latestTopicobject | nullrequired

Show properties

Any of:

object

isV2booleanrequired

lastMessageAtstring<date-time>

topicIdstring<uuid>required

Show properties

Any of:

string<uuid>

string<uuid>

string<uuid>

string<uuid>

topicTitlestringrequired

topicTypestring | nullrequired

Show properties

Any of:

string

string

null

null

null

null

messageCountintegerrequired

primaryEmailstring<email> | nullrequired

Show properties

Any of:

string<email>

string<email>

null

null

sourcesstring[]required

titlestring | nullrequired

Show properties

Any of:

string

string

null

null

weeklyActivityinteger[]required

limitintegerrequired

The page size used for this response.

pageintegerrequired

The 1-based page number returned.

totalCountintegerrequired

Total number of items matching the query, across all pages.

min 0

400

Invalid request (validation failed).

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

401

Missing or invalid API key.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

403

The API key does not have access to this resource.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

404

The requested resource was not found.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

429

Rate limit exceeded.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

500

Internal server error.

codestringrequired

Machine-readable error code, e.g. NOT_FOUND.

dataany

Optional structured error details.

definedbooleanrequired

True if the error was declared in the procedure contract.

messagestringrequired

Human-readable error message.

statusintegerrequired

HTTP status code.

Try it

Server

Base URLCustom base URLOverrides the selected server when set.

Authorization

Bearer tokenRemember on this deviceInclude my values in samples

Parameters

pagequerylimitquerysearchquerysortByquerysortOrderqueryecosystemTagsqueryFilter by ecosystem tags (OR match)companyIdqueryFilter to people currently associated with this company

Request

curl -X GET 'https://api.modem.dev/v1/people' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json'

const response = await fetch("https://api.modem.dev/v1/people", {
  method: "GET",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json"
  }
});

import requests

response = requests.get(
    "https://api.modem.dev/v1/people",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json"
    },
)

Response

{
  "data": [
    {
      "avatarUrl": "http://example.com",
      "company": {
        "domain": "string",
        "id": "string",
        "logoUrl": "string",
        "name": "string"
      },
      "displayName": "string",
      "id": "string",
      "identities": [
        {
          "platform": "string",
          "platformId": "string"
        }
      ],
      "identityCount": 0,
      "isVip": true,
      "lastSeenAt": "2019-08-24T14:15:22Z",
      "latestTopic": {
        "isV2": true,
        "lastMessageAt": "2019-08-24T14:15:22Z",
        "topicId": "97b608a9-302e-4387-a5f4-fd35969cdc21",
        "topicTitle": "string",
        "topicType": "string"
      },
      "messageCount": 0,
      "primaryEmail": "user@example.com",
      "sources": [
        "string"
      ],
      "title": "string",
      "weeklyActivity": [
        0
      ]
    }
  ],
  "limit": 1,
  "page": 1,
  "totalCount": 0
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}

{
  "code": "NOT_FOUND",
  "data": null,
  "defined": true,
  "message": "string",
  "status": 404
}