Create people

Create one or more people. Batch-first: always pass a people array (use a single-element array to create one person). Supports partial success - each person is created independently.

POST/people

Authorization

AuthorizationBearer token · headerrequired

Organization API key (modem_…).

Header parameters

Idempotency-Keystring

Replays a successful mutating request for 24 hours. Reuse with a different payload returns 409.

max length 255

Request body

requiredapplication/json

peopleobject[]required

min items 1 · max items 50

Show properties

Array of object

avatarUrlstring<uri> | null

Show properties

Any of:

string<uri>

string<uri>

null

null

connectionsobject

Show properties

githubstring | null

Show properties

Any of:

string

string

null

null

linkedinstring | null

Show properties

Any of:

string

string

null

null

phonestring | null

Show properties

Any of:

string

string

null

null

titlestring | null

Show properties

Any of:

string

string

null

null

twitterstring | null

Show properties

Any of:

string

string

null

null

websitestring | null

Show properties

Any of:

string

string

null

null

descriptionstring | null

Show properties

Any of:

string

string

null

null

displayNamestringrequired

min length 1 · max length 255

isVipboolean

primaryEmailstring<email> | null

Show properties

Any of:

string<email>

string<email>

null

null

Responses

200

resultsobject[]required

Show properties

Array of object

dataobject

Show properties

avatarUrlstring<uri> | nullrequired

Avatar image URL for the person.

Show properties

Any of:

string<uri>

string<uri>

null

null

connectionsobjectrequired

Show properties

githubstring | nullrequired

Show properties

Any of:

string

string

null

null

linkedinstring | nullrequired

Show properties

Any of:

string

string

null

null

phonestring | nullrequired

Show properties

Any of:

string

string

null

null

titlestring | nullrequired

Show properties

Any of:

string

string

null

null

twitterstring | nullrequired

Show properties

Any of:

string

string

null

null

websitestring | nullrequired

Show properties

Any of:

string

string

null

null

descriptionstring | nullrequired

Show properties

Any of:

string

string

null

null

displayNamestringrequired

Display name for the person.

idstringrequired

matches ^\d+$

isVipbooleanrequired

primaryEmailstring<email> | nullrequired

Show properties

Any of:

string<email>

string<email>

null

null

displayNamestringrequired

errorstring

successbooleanrequired

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.

409

The request conflicts with an existing resource or idempotency operation.

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

Idempotency-KeyheaderReplays a successful mutating request for 24 hours. Reuse with a different payload returns 409.

Bodyapplication/json

Request body

Request

curl -X POST 'https://api.modem.dev/v1/people' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "people": [
    {
      "avatarUrl": "http://example.com",
      "connections": {
        "github": "string",
        "linkedin": "string",
        "phone": "string",
        "title": "string",
        "twitter": "string",
        "website": "string"
      },
      "description": "string",
      "displayName": "string",
      "isVip": true,
      "primaryEmail": "user@example.com"
    }
  ]
}'

const response = await fetch("https://api.modem.dev/v1/people", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"people\": [\n    {\n      \"avatarUrl\": \"http://example.com\",\n      \"connections\": {\n        \"github\": \"string\",\n        \"linkedin\": \"string\",\n        \"phone\": \"string\",\n        \"title\": \"string\",\n        \"twitter\": \"string\",\n        \"website\": \"string\"\n      },\n      \"description\": \"string\",\n      \"displayName\": \"string\",\n      \"isVip\": true,\n      \"primaryEmail\": \"user@example.com\"\n    }\n  ]\n}"
});

import requests

response = requests.post(
    "https://api.modem.dev/v1/people",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"people\": [\n    {\n      \"avatarUrl\": \"http://example.com\",\n      \"connections\": {\n        \"github\": \"string\",\n        \"linkedin\": \"string\",\n        \"phone\": \"string\",\n        \"title\": \"string\",\n        \"twitter\": \"string\",\n        \"website\": \"string\"\n      },\n      \"description\": \"string\",\n      \"displayName\": \"string\",\n      \"isVip\": true,\n      \"primaryEmail\": \"user@example.com\"\n    }\n  ]\n}",
)

Response

{
  "results": [
    {
      "data": {
        "avatarUrl": "http://example.com",
        "connections": {
          "github": "string",
          "linkedin": "string",
          "phone": "string",
          "title": "string",
          "twitter": "string",
          "website": "string"
        },
        "description": "string",
        "displayName": "string",
        "id": "string",
        "isVip": true,
        "primaryEmail": "user@example.com"
      },
      "displayName": "string",
      "error": "string",
      "success": true
    }
  ]
}

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

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