Create Person

post/v1/people

Creates a person in the caller's workspace, optionally linking emails, phones, web links, companies, and an avatar via relationships plus a matching included block. Side effect: inserts the person row and any requested junctions. Deduplication may resolve to an existing person when external_person_id matches.

Requires a bearer token: Authorization: Bearer <token>.

Request

cURL
curl -X POST https://api.wellapp.ai/v1/people \
  -H "Authorization: Bearer $WELL_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "data": {
    "type": "people",
    "attributes": {
      "first_name": "Dani",
      "last_name": "Park",
      "job_title": "Head of Finance"
    },
    "relationships": {
      "emails": {
        "data": [
          {
            "type": "email",
            "id": "local-email-1"
          }
        ]
      },
      "companies": {
        "data": [
          {
            "type": "company",
            "id": "b2c3d4e5-6f70-4812-93a4-b5c6d7e8f9a0",
            "meta": {
              "relationship_type": "employee"
            }
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "email",
      "id": "local-email-1",
      "attributes": {
        "value": "dani@foldspace.ai",
        "label": "work",
        "is_primary": true
      }
    }
  ]
}'
Request body
{
  "data": {
    "type": "people",
    "attributes": {
      "first_name": "Dani",
      "last_name": "Park",
      "job_title": "Head of Finance"
    },
    "relationships": {
      "emails": {
        "data": [
          {
            "type": "email",
            "id": "local-email-1"
          }
        ]
      },
      "companies": {
        "data": [
          {
            "type": "company",
            "id": "b2c3d4e5-6f70-4812-93a4-b5c6d7e8f9a0",
            "meta": {
              "relationship_type": "employee"
            }
          }
        ]
      }
    }
  },
  "included": [
    {
      "type": "email",
      "id": "local-email-1",
      "attributes": {
        "value": "dani@foldspace.ai",
        "label": "work",
        "is_primary": true
      }
    }
  ]
}

Responses

201 — The created person with relationships and included resources.

{
  "data": {
    "type": "people",
    "id": "d5e6f7a8-9b0c-41d2-83e4-f5a6b7c8d9e0",
    "attributes": {
      "full_name": "Dani Park",
      "first_name": "Dani",
      "last_name": "Park",
      "job_title": "Head of Finance",
      "created_at": "2026-01-12T09:31:00.000Z",
      "updated_at": "2026-05-18T11:22:09.000Z"
    },
    "relationships": {
      "companies": {
        "data": [
          {
            "type": "companies",
            "id": "b2c3d4e5-6f70-4812-93a4-b5c6d7e8f9a0"
          }
        ]
      }
    }
  },
  "included": []
}

400 — Bad Request

{
  "code": "BAD_REQUEST",
  "status": 400,
  "title": "Bad Request",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

401 — Unauthorized

{
  "code": "UNAUTHORIZED",
  "status": 401,
  "title": "Unauthorized",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}

403 — Forbidden

{
  "code": "FORBIDDEN",
  "status": 403,
  "title": "Forbidden",
  "message": "See title.",
  "meta": {
    "trace_id": "a1b2c3",
    "log_id": "a1b2c3"
  }
}