People

The People API allows you to manage contacts and individuals within the Meridian CRM system.

Authentication

All requests must include a Bearer token in the HTTP header:

Authorization: Bearer ACCESS_TOKEN

Endpoints

List People

Description: Retrieve a list of people from the user's organization.

Endpoint: GET api/public/v1/people/

Optional Query Parameters:

search (string): Filter by first name, last name, or email
ordering (string): Order results by specific fields (e.g., first_name, created for descending)
company (UUID): Filter by associated company

Response Example:

[
  {
    "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@acme-corp.com",
    "phone": "+1-555-123-4567",
    "created": "2025-04-24T08:44:27.574699Z",
    "modified": "2025-04-24T08:44:27.574709Z",
    "company_associations": [
      {
        "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
        "company": {
          "id": "bfcd725e-88da-41cd-8d9c-6aed5dda1a4a",
          "title": "Acme Corp"
        },
        "is_primary": true,
        "relation": "CTO"
      }
    ]
  }
]

Get Person Details

Description: Retrieve details for a specific person.

Endpoint: GET api/public/v1/people/{id}/

Response Example:

{
  "id": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@acme-corp.com",
  "phone": "+1-555-123-4567",
  "created": "2025-04-24T08:44:27.574699Z",
  "modified": "2025-04-24T08:44:27.574709Z",
  "enrichment_status": "completed",
  "organization": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "company_associations": [
    {
      "id": "5a6b7c8d-9e0f-1a2b-3c4d-5e6f7a8b9c0d",
      "company": {
        "id": "bfcd725e-88da-41cd-8d9c-6aed5dda1a4a",
        "title": "Acme Corp",
        "website": "<https://acme-corp.com/>"
      },
      "is_primary": true,
      "relation": "CTO"
    }
  ],
  "deals": [
    {
      "id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
      "title": "Enterprise Software License",
      "relation": "Decision Maker"
    }
  ],
  "meetings": [
    {
      "id": "7e8f9a0b-1c2d-3e4f-5a6b-7c8d9e0f1a2b",
      "title": "Deal Discussion",
      "start_time": "2025-05-15T10:00:00Z"
    }
  ],
  "emails": [
    {
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "subject": "Meeting Follow-up",
      "date": "2025-04-30T14:22:18.123456Z"
    }
  ]
}

Create Person

Description: Create a new person.

Endpoint: POST api/public/v1/people/

Request Example:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@example.com",
  "phone": "+1-555-987-6543",
  "company_associations": [
    {
      "company": "bfcd725e-88da-41cd-8d9c-6aed5dda1a4a",
      "is_primary": true,
      "relation": "CEO"
    }
  ]
}

Response: Returns the created person object with HTTP 201 status code.

Update Person

Description: Update an existing person.

Endpoint: PUT api/public/v1/people/{id}/

Request Example:

{
  "first_name": "John",
  "last_name": "Doe",
  "email": "john.doe@updated-email.com",
  "phone": "+1-555-987-6543"
}

Response: Returns the updated person object.

Delete Person

Description: Delete a person.

Endpoint: DELETE api/public/v1/people/{id}/

Response: Returns HTTP 204 No Content on success.

Manage Company Associations

Description: Add, update, or remove company associations for a person.

Endpoint: POST api/public/v1/people/company-associations/

Request Example:

{
  "person": "3c4d5e6f-7a8b-9c0d-1e2f-3a4b5c6d7e8f",
  "company": "bfcd725e-88da-41cd-8d9c-6aed5dda1a4a",
  "is_primary": true,
  "relation": "CTO"
}

Response: Returns the created company association object with HTTP 201 status code.

Update Endpoint: PUT api/public/v1/people/company-associations/{id}/

Request Example:

{
  "is_primary": false,
  "relation": "Former CTO"
}

Response: Returns the updated company association object.

Delete Endpoint: DELETE api/public/v1/people/company-associations/{id}/

Response: Returns HTTP 204 No Content on success.

Enrich Person Data

Description: Trigger data enrichment for a person to fetch additional information.

Endpoint: POST api/public/v1/people/{id}/enrich/

Response: Returns HTTP 202 Accepted on successful initiation of the enrichment process.

Metadata Endpoints

Person Metadata

Description: Retrieve metadata for person fields.

Endpoint: GET api/public/v1/people/metadata/

Request Example:

{
  "fields": [
    {
      "label": "First Name",
      "name": "first_name",
      "type": "string",
      "createable": true,
      "updateable": true,
      "required": true
    },
    {
      "label": "Last Name",
      "name": "last_name",
      "type": "string",
      "createable": true,
      "updateable": true,
      "required": true
    },
    {
      "label": "Email",
      "name": "email",
      "type": "email",
      "createable": true,
      "updateable": true,
      "required": true
    },
    {
      "label": "Phone",
      "name": "phone",
      "type": "phone",
      "createable": true,
      "updateable": true,
      "required": false
    },
    {
      "label": "Enrichment Status",
      "name": "enrichment_status",
      "type": "picklist",
      "createable": false,
      "updateable": false,
      "required": false,
      "select_options": [
        {"label": "Pending", "value": "pending"},
        {"label": "Completed", "value": "completed"},
        {"label": "Failed", "value": "failed"}
      ]
    },
    {
      "label": "Created",
      "name": "created",
      "type": "datetime",
      "createable": false,
      "updateable": false,
      "required": false
    },
    {
      "label": "Modified",
      "name": "modified",
      "type": "datetime",
      "createable": false,
      "updateable": false,
      "required": false
    }
  ]
}

Person Company Association Metadata

Description: Retrieve metadata for person company association fields.

Endpoint: GET api/public/v1/people/company-associations/metadata/

Request Example:

{
  "fields": [
    {
      "label": "Person",
      "name": "person",
      "type": "reference",
      "reference_to": "person",
      "createable": true,
      "updateable": false,
      "required": true
    },
    {
      "label": "Company",
      "name": "company",
      "type": "reference",
      "reference_to": "company",
      "createable": true,
      "updateable": true,
      "required": true
    },
    {
      "label": "Is Primary",
      "name": "is_primary",
      "type": "boolean",
      "createable": true,
      "updateable": true,
      "required": false
    },
    {
      "label": "Relation",
      "name": "relation",
      "type": "string",
      "createable": true,
      "updateable": true,
      "required": false
    }
  ]
}

Error Responses

400 Bad Request: Invalid request parameters
401 Unauthorized: Missing or invalid authentication
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
500 Internal Server Error: Server-side error

Data Models

Person

Field

Type

Description

UUID

Unique identifier

first_name

String

First name

last_name

String

Last name

String

Email address

phone

String

Phone number

organization

UUID

Reference to organization

enrichment_status

String

Status of data enrichment (pending/completed/failed)

created

DateTime

Creation timestamp

modified

DateTime

Last modification timestamp

Person Company Association

Field

Type

Description

UUID

Unique identifier

person

UUID

Reference to person

company

UUID

Reference to company

is_primary

Boolean

Whether this is the primary company for the person

relation

String

Person's role or relation to the company

created

DateTime

Creation timestamp

modified

DateTime

Last modification timestamp

Notes

Users

People

Authentication

Endpoints

List People

Get Person Details

Create Person

Update Person

Delete Person

Manage Company Associations

Enrich Person Data

Metadata Endpoints

Person Metadata

Person Company Association Metadata

Error Responses

Data Models

Person

Person Company Association

Discover how Meridian can streamline deal sourcing and enhance your decision-making