Companies API

Learn how to manage companies in AchieveApex using the REST API.

Overview

The Companies API allows you to manage companies within your organization. You can list, retrieve, create, update, and delete companies.

Base Endpoint

/companies

Company Object

The company object contains information about a company in your organization.

Company Object

{
  "id": 101,
  "name": "Acme Corporation",
  "organization_id": 456,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z",
  "deleted_at": null,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "description": "Leading provider of innovative solutions",
  "website": "https://www.acmecorp.example.com",
  "industry": "Technology",
  "size": "Medium",
  "custom_fields_by_name": {
    "Annual Revenue": "$10M - $50M",
    "Founded Year": "2010"
  },
  "creator": {
    "id": 789,
    "first_name": "Admin",
    "last_name": "User"
  },
  "owner": {
    "id": 789,
    "first_name": "Admin",
    "last_name": "User"
  }
}

List Companies

Retrieve a list of companies for your organization with optional filtering and pagination.

Request

GET /companies

curl -X GET https://api.achieveapex.com/companies \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "organization_id": 456,
      "$limit": 25,
      "$skip": 0,
      "$sort": { "created_at": -1 },
      "fastJoinForCompanyList": true
    }
  }'

Response

{
  "total": 50,
  "limit": 25,
  "skip": 0,
  "data": [
    {
      "id": 101,
      "name": "Acme Corporation",
      "organization_id": 456,
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-01T00:00:00.000Z",
      "deleted_at": null,
      "created_by_user_id": 789,
      "owned_by_user_id": 789,
      "creator": {
        "id": 789,
        "first_name": "Admin",
        "last_name": "User"
      },
      "owner": {
        "id": 789,
        "first_name": "Admin",
        "last_name": "User"
      }
    },
    // Additional companies...
  ]
}

Query Parameters

Parameter	Type	Description
organization_id	Number	ID of the organization to fetch companies for (required)
$limit	Number	Number of companies to return (default: 10)
$skip	Number	Number of companies to skip (for pagination)
$sort	Object	Sort criteria (e.g., `{ "created_at": -1 }` for newest first)
fastJoinForCompanyList	Boolean	Include associated data like creator and owner (recommended)

Get a Company

Retrieve a single company by ID.

Request

GET /companies/:id

curl -X GET https://api.achieveapex.com/companies/101 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "id": 101,
  "name": "Acme Corporation",
  "organization_id": 456,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-01T00:00:00.000Z",
  "deleted_at": null,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "description": "Leading provider of innovative solutions",
  "website": "https://www.acmecorp.example.com",
  "industry": "Technology",
  "size": "Medium",
  "custom_fields_by_name": {
    "Annual Revenue": "$10M - $50M",
    "Founded Year": "2010"
  },
  "creator": {
    "id": 789,
    "first_name": "Admin",
    "last_name": "User"
  },
  "owner": {
    "id": 789,
    "first_name": "Admin",
    "last_name": "User"
  }
}

Create a Company

Create a new company in your organization.

Request

POST /companies

curl -X POST https://api.achieveapex.com/companies \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organization_id": 456,
    "name": "New Horizon Inc",
    "description": "Emerging tech company",
    "website": "https://newhorizon.example.com",
    "industry": "Software",
    "size": "Small",
    "owned_by_user_id": 789
  }'

Response

{
  "id": 102,
  "name": "New Horizon Inc",
  "organization_id": 456,
  "created_at": "2023-01-02T00:00:00.000Z",
  "updated_at": "2023-01-02T00:00:00.000Z",
  "deleted_at": null,
  "created_by_user_id": 789,
  "owned_by_user_id": 789,
  "description": "Emerging tech company",
  "website": "https://newhorizon.example.com",
  "industry": "Software",
  "size": "Small"
}

Request Parameters

Parameter	Type	Required	Description
organization_id	Number	Yes	ID of the organization to create the company in
name	String	Yes	Name of the company
description	String	No	Description of the company
website	String	No	Website URL of the company
industry	String	No	Industry the company operates in
size	String	No	Size of the company (e.g., Small, Medium, Large)
owned_by_user_id	Number	No	ID of the user who owns this company (defaults to creator)

Update a Company

Update an existing company's information.

Request

PATCH /companies/:id

curl -X PATCH https://api.achieveapex.com/companies/101 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation Global",
    "description": "Global leader in innovative solutions",
    "industry": "Technology & Software",
    "size": "Large",
    "owned_by_user_id": 790
  }'

Response

{
  "id": 101,
  "name": "Acme Corporation Global",
  "organization_id": 456,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-03T00:00:00.000Z",
  "deleted_at": null,
  "created_by_user_id": 789,
  "owned_by_user_id": 790,
  "description": "Global leader in innovative solutions",
  "website": "https://www.acmecorp.example.com",
  "industry": "Technology & Software",
  "size": "Large"
}

Delete a Company

Mark a company as deleted (soft delete).

Request

DELETE /companies/:id

curl -X DELETE https://api.achieveapex.com/companies/101 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json"

Response

{
  "id": 101,
  "name": "Acme Corporation Global",
  "organization_id": 456,
  "created_at": "2023-01-01T00:00:00.000Z",
  "updated_at": "2023-01-03T12:00:00.000Z",
  "deleted_at": "2023-01-03T12:00:00.000Z",
  "created_by_user_id": 789,
  "owned_by_user_id": 790,
  "description": "Global leader in innovative solutions",
  "website": "https://www.acmecorp.example.com",
  "industry": "Technology & Software",
  "size": "Large"
}

Search Companies

Search for companies by name or other attributes.

Request

POST /companies
Headers: X-Service-Method: search

curl -X POST https://api.achieveapex.com/companies \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Service-Method: search" \
  -d '{
    "searchTerm": "acme",
    "organization_id": 456,
    "$limit": 5
  }'

Response

{
  "data": [
    {
      "id": 101,
      "name": "Acme Corporation Global",
      "organization_id": 456,
      "created_at": "2023-01-01T00:00:00.000Z",
      "updated_at": "2023-01-03T00:00:00.000Z"
    }
  ]
}

Search Parameters

Parameter	Type	Required	Description
searchTerm	String	Yes	The term to search for (minimum 2 characters)
organization_id	Number	Yes	ID of the organization to search companies in
$limit	Number	No	Maximum number of results to return

Error Handling

The Companies API returns standard HTTP status codes and error messages.

Error Response

{
  "name": "NotFound",
  "message": "No record found for id '999'",
  "code": 404,
  "className": "not-found"
}

Status Code	Description
400 Bad Request	Invalid parameters or request
401 Unauthorized	Missing or invalid authentication
403 Forbidden	Not authorized to access this organization's companies
404 Not Found	Company not found
500 Internal Server Error	Server error

Companies API

Overview

Company Object

List Companies

Query Parameters

Get a Company

Create a Company

Request Parameters

Update a Company

Delete a Company

Search Companies

Search Parameters

Error Handling

Related Documentation

Report an issue with this documentation