Companies

The Companies API allows you to manage company information within the Meridian CRM system.

Authentication

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

Authorization: Bearer ACCESS_TOKEN

Endpoints

List Companies

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

Endpoint: GET api/public/v1/companies/

Optional Query Parameters:

search (string): Filter by company title or website
ordering (string): Order results by specific fields (e.g., title, created for descending)
type (UUID): Filter by company type
priority (UUID): Filter by company priority
stage (UUID): Filter by company stage

Response Example:

[
  {
    "id": "bfcd725e-88da-41cd-8d9c-6aed5dda1a4a",
    "created": "2025-04-24T08:44:27.574699Z",
    "description": "Description",
    "modified": "2025-04-24T08:44:27.574709Z",
    "priority": "a650c273-9097-4e2b-8959-7b6588920d6b",
    "title": "Acme Corp",
    "type": "b215c217-248f-4d11-be17-d47f1a0b644e",
    "website": "<https://acme-corp.com/>",
    "owner": "7f8d9e10-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "stage": {
      "id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
      "title": "Lead"
    },
    "users": [
      {
        "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
        "first_name": "John",
        "last_name": "Doe",
        "email": "john.doe@example.com"
      }
    ]
  }
]

Get Company Details

Description: Retrieve details for a specific company.

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

Response Example:

{
  "id": "bfcd725e-88da-41cd-8d9c-6aed5dda1a4a",
  "created": "2025-04-24T08:44:27.574699Z",
  "description": "Description",
  "modified": "2025-04-24T08:44:27.574709Z",
  "priority": "a650c273-9097-4e2b-8959-7b6588920d6b",
  "title": "Acme Corp",
  "type": "b215c217-248f-4d11-be17-d47f1a0b644e",
  "website": "<https://acme-corp.com/>",
  "owner": {
    "id": "7f8d9e10-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
    "first_name": "Jane",
    "last_name": "Smith",
    "email": "jane.smith@example.com"
  },
  "stage": {
    "id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
    "title": "Lead"
  },
  "users": [
    {
      "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    }
  ],
  "detail_field_values": [
    {
      "id": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
      "company_detail_field": "1e2f3a4b-5c6d-7e8f-9a0b-1c2d3e4f5a6b",
      "value": "Technology"
    }
  ],
  "last_interaction": "2025-04-30T14:22:18.123456Z",
  "last_interaction_object_type": "email"
}

Create Company

Description: Create a new company.

Endpoint: POST api/public/v1/companies/

Request Example:

{
  "title": "New Company Inc.",
  "description": "A new company in our CRM",
  "website": "<https://newcompany.com>",
  "type": "b215c217-248f-4d11-be17-d47f1a0b644e",
  "priority": "a650c273-9097-4e2b-8959-7b6588920d6b",
  "stage_object_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
  "users": ["1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"]
}

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

Update Company

Description: Update an existing company.

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

Request Example:

{
  "title": "Updated Company Name",
  "description": "Updated description",
  "website": "<https://updatedwebsite.com>",
  "type": "b215c217-248f-4d11-be17-d47f1a0b644e",
  "priority": "a650c273-9097-4e2b-8959-7b6588920d6b",
  "stage_object_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
  "users": ["1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"]
}

Response: Returns the updated company object.

Delete Company

Description: Delete a company.

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

Response: Returns HTTP 204 No Content on success.

Create Company with Deal

Description: Create a company and associated deal in one operation.

Endpoint: POST api/public/v1/companies/create-company-with-deal/

Request Example:

{
  "title": "New Company Inc.",
  "description": "A new company in our CRM",
  "website": "<https://newcompany.com>",
  "type": "b215c217-248f-4d11-be17-d47f1a0b644e",
  "priority": "a650c273-9097-4e2b-8959-7b6588920d6b",
  "stage_object_id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
  "users": ["1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"],
  "deal_title": "New Deal",
  "deal_description": "Description of the new deal",
  "deal_members": ["1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"],
  "deal_kpi_values": [
    {
      "kpi": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
      "value": "1000000"
    }
  ]
}

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

Get Company Last Interaction

Description: Retrieve the last interaction (email or meeting) for a company.

Endpoint: GET api/public/v1/companies/{id}/last-interaction/

Request Example:

{
  "email": {
    "id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
    "subject": "Meeting Follow-up",
    "date": "2025-04-30T14:22:18.123456Z",
    "recipients": [
      {
        "user": {
          "id": "7f8d9e10-1a2b-3c4d-5e6f-7a8b9c0d1e2f",
          "first_name": "Jane",
          "last_name": "Smith"
        },
        "person": null
      }
    ]
  },
  "meeting": null
}

Company Types API

List Company Types

Description: Retrieve a list of company types.

Endpoint: GET api/public/v1/companies/types/

Request Example:

[
  {
    "id": "b215c217-248f-4d11-be17-d47f1a0b644e",
    "title": "Prospect",
    "color": "#FF5733",
    "organization": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
  }
]

Create Company Type

Description: Create a new company type.

Endpoint: POST api/public/v1/companies/types/

Request Example:

{
  "title": "Partner",
  "color": "#33FF57"
}

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

Company Priorities API

List Company Priorities

Description: Retrieve a list of company priorities.

Endpoint: GET api/public/v1/companies/priorities/

Request Example:

[
  {
    "id": "a650c273-9097-4e2b-8959-7b6588920d6b",
    "title": "High",
    "color": "#FF0000",
    "order": 1,
    "organization": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
  }
]

Create Company Priority

Description: Create a new company priority.

Endpoint: POST api/public/v1/companies/priorities/

Request Example:

{
  "title": "Medium",
  "color": "#FFFF00",
  "order": 2
}

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

Company Stages API

List Company Stages

Description: Retrieve a list of company stages.

Endpoint: GET api/public/v1/companies/stages/

Request Example:

[
  {
    "id": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
    "title": "Lead",
    "color": "#3366FF",
    "order": 1,
    "organization": "9a8b7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d"
  }
]

Create Company Stage

Description: Create a new company stage.

Endpoint: POST api/public/v1/companies/stages/

Request Example:

{
  "title": "Qualified",
  "color": "#33CCFF",
  "order": 2
}

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

Metadata Endpoints

Get Company Fields Metadata

Description: Retrieve metadata about company fields, including field names, types, and whether they are required, createable, or updateable.

Endpoint: GET api/public/v1/companies/metadata/fields/

Request Example:

{
  "fields": [
    {
      "name": "title",
      "label": "Company Name",
      "type": "string",
      "required": true,
      "createable": true,
      "updateable": true
    },
    {
      "name": "description",
      "label": "Description",
      "type": "text",
      "required": false,
      "createable": true,
      "updateable": true
    },
    {
      "name": "website",
      "label": "Website",
      "type": "url",
      "required": false,
      "createable": true,
      "updateable": true
    },
    {
      "name": "type",
      "label": "Company Type",
      "type": "reference",
      "required": false,
      "createable": true,
      "updateable": true,
      "reference_to": "CompanyType",
      "select_options": [
        {
          "value": "b215c217-248f-4d11-be17-d47f1a0b644e",
          "label": "Prospect"
        },
        {
          "value": "c326d328-359f-5e22-cf28-e58f2b1c755f",
          "label": "Customer"
        }
      ]
    },
    {
      "name": "priority",
      "label": "Priority",
      "type": "reference",
      "required": false,
      "createable": true,
      "updateable": true,
      "reference_to": "CompanyPriority",
      "select_options": [
        {
          "value": "a650c273-9097-4e2b-8959-7b6588920d6b",
          "label": "High"
        },
        {
          "value": "b761d384-a1a8-5f3c-96a6-8c6991a31d7c",
          "label": "Medium"
        }
      ]
    },
    {
      "name": "stage_object_id",
      "label": "Stage",
      "type": "reference",
      "required": false,
      "createable": true,
      "updateable": true,
      "reference_to": "CompanyStage",
      "select_options": [
        {
          "value": "3f4a5b6c-7d8e-9f0a-1b2c-3d4e5f6a7b8c",
          "label": "Lead"
        },
        {
          "value": "4f5a6b7c-8d9e-0f1a-2b3c-4d5e6f7a8b9c",
          "label": "Qualified"
        }
      ]
    },
    {
      "name": "owner",
      "label": "Owner",
      "type": "reference",
      "required": false,
      "createable": true,
      "updateable": true,
      "reference_to": "User"
    },
    {
      "name": "users",
      "label": "Team Members",
      "type": "array",
      "required": false,
      "createable": true,
      "updateable": true,
      "items_type": "reference",
      "reference_to": "User"
    }
  ]
}

Get Company Type Fields Metadata

Description: Retrieve metadata about company type fields.

Endpoint: GET api/public/v1/companies/types/metadata/fields/

Request Example:

{
  "fields": [
    {
      "name": "title",
      "label": "Type Name",
      "type": "string",
      "required": true,
      "createable": true,
      "updateable": true
    },
    {
      "name": "color",
      "label": "Color",
      "type": "string",
      "required": true,
      "createable": true,
      "updateable": true
    }
  ]
}

Get Company Priority Fields Metadata

Description: Retrieve metadata about company priority fields.

Endpoint: GET api/public/v1/companies/priorities/metadata/fields/

Request Example:

{
  "fields": [
    {
      "name": "title",
      "label": "Priority Name",
      "type": "string",
      "required": true,
      "createable": true,
      "updateable": true
    },
    {
      "name": "color",
      "label": "Color",
      "type": "string",
      "required": true,
      "createable": true,
      "updateable": true
    },
    {
      "name": "order",
      "label": "Display Order",
      "type": "integer",
      "required": true,
      "createable": true,
      "updateable": true
    }
  ]
}

Get Company Stage Fields Metadata

Description: Retrieve metadata about company stage fields.

Endpoint: GET api/public/v1/companies/stages/metadata/fields/

Request Example:

{
  "fields": [
    {
      "name": "title",
      "label": "Stage Name",
      "type": "string",
      "required": true,
      "createable": true,
      "updateable": true
    },
    {
      "name": "color",
      "label": "Color",
      "type": "string",
      "required": true,
      "createable": true,
      "updateable": true
    },
    {
      "name": "order",
      "label": "Display Order",
      "type": "integer",
      "required": true,
      "createable": true,
      "updateable": true
    }
  ]
}

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

Company

Field

Type

Description

UUID

Unique identifier

title

String

Company name

description

String

Company description

website

String

Company website URL

type

UUID

Reference to company type

priority

UUID

Reference to company priority

stage_object_id

UUID

Reference to company stage

owner

UUID

Reference to user who owns the company

organization

UUID

Reference to organization

users

Array of UUIDs

Users associated with the company

created

DateTime

Creation timestamp

modified

DateTime

Last modification timestamp

last_interaction

DateTime

Last interaction timestamp

last_interaction_object_type

String

Type of last interaction (email/meeting)

Company Type

Field

Type

Description

UUID

Unique identifier

title

String

Type name

color

String

Hex color code

organization

UUID

Reference to organization

Company Priority

Field

Type

Description

UUID

Unique identifier

title

String

Priority name

color

String

Hex color code

order

Integer

Display order

organization

UUID

Reference to organization

Company Priority

Field

Type

Description

UUID

Unique identifier

title

String

Stage name

color

String

Hex color code

order

Integer

Display order

organization

UUID

Reference to organization

Authentication

Deals

Authentication

Endpoints

Company Types API

Company Priorities API

Companies

Authentication

Endpoints

List Companies

Get Company Details

Create Company

Update Company

Delete Company

Create Company with Deal

Get Company Last Interaction

Company Types API

List Company Types

Create Company Type

Company Priorities API

List Company Priorities

Create Company Priority

Company Stages API

List Company Stages

Create Company Stage

Metadata Endpoints

Get Company Fields Metadata

Get Company Type Fields Metadata

Get Company Priority Fields Metadata

Get Company Stage Fields Metadata

Error Responses

Data Models

Company

Company Type

Company Priority

Company Priority

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