Difference between revisions of "API:Companies:Create"

From docs
Jump to: navigation, search
(Created page with "== API » Create Companies == '''URL:''' <nowiki>https://app.callproof.com/api/companies/new/</nowiki> '''Method:''' POST '''Required Fields:''' * '''''api_key[key...")
 
 
Line 1: Line 1:
 
== [[API]] &#187; Create Companies ==
 
== [[API]] &#187; Create Companies ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/companies/new/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' POST
+
=== Endpoint ===
 +
/api/companies/new/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Creates a new contact company (account/company record) in your CallProof company. Use this to add a company name that contacts can later be associated with.
  
−
* '''''api_key[key]''''' - API Key
+
=== HTTP Method ===
−
* '''''api_key[secret]''''' - API Key Secret
+
POST
−
* '''''companies[name]''''' - Companies name
 
  
−
'''Data Returned:'''
+
=== Headers ===
 +
{| class="wikitable"
 +
! Header !! Required !! Description
 +
|-
 +
| Content-Type || Yes || Must be <code>application/json</code>.
 +
|}
  
−
* '''''results''''' - Companies details
+
=== Security ===
−
* '''''errors''''' - Array of errors produced by the request
+
* '''Yes''' – Requires a valid API key and secret with permission to create companies. Credentials are sent in the request body.
−
* '''''code''''' - HTTP request status
+
 
 +
=== Parameters ===
 +
 
 +
==== Path Parameters ====
 +
None.
 +
 
 +
==== Query Parameters ====
 +
None.
 +
 
 +
==== Request Body ====
 +
{| class="wikitable"
 +
! Parameter !! Type !! Required !! Description
 +
|-
 +
| api_key || object || Yes || Authentication credentials object.
 +
|-
 +
| api_key.key || string || Yes || Public API key assigned to your CallProof account.
 +
|-
 +
| api_key.secret || string || Yes || Private API secret paired with the API key.
 +
|-
 +
| companies || object || Yes || Company creation payload.
 +
|-
 +
| companies.name || string || Yes || Name of the company to create. Cannot be empty.
 +
|}
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/companies/new/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "companies": {
 +
      "name": "Acme Corp"
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Indicates the company was created successfully. The response returns the new company details.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || object || Newly created company details.
 +
|-
 +
| results.id || integer || Unique identifier for the company.
 +
|-
 +
| results.primary_contact || integer or string || Primary contact identifier associated with the company, or empty if none is set.
 +
|-
 +
| results.name || string || Company name.
 +
|-
 +
| results.updated || string || Date and time the company was last updated (<code>YYYY-MM-DD HH:MM:SS</code>).
 +
|-
 +
| results.created || string || Date and time the company was created (<code>YYYY-MM-DD HH:MM:SS</code>).
 +
|-
 +
| errors || array || Empty list when the request succeeds.
 +
|-
 +
| code || integer || HTTP-style status value; <code>200</code> on success.
 +
|}
 +
 
 +
Example response:
 +
<pre>
 +
{
 +
  "results": {
 +
    "id": 321,
 +
    "primary_contact": "",
 +
    "name": "Acme Corp",
 +
    "updated": "2024-06-15 14:30:00",
 +
    "created": "2024-06-15 14:30:00"
 +
  },
 +
  "errors": [],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Notes ===
 +
* Only the company name is required to create a company record.
 +
* A newly created company typically has no primary contact until one is assigned later.
 +
* This creates a contact company/account record within your CallProof company, not a new CallProof tenant.
 +
* Field-level validation failures typically return HTTP <code>200</code> with details in the <code>errors</code> array and an empty <code>results</code> object.
 +
* To update an existing company, use <code>/api/companies/update/</code>.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 200 || Validation issue – The company name is missing/empty, or the company could not be created. Details are provided in the <code>errors</code> array.
 +
|-
 +
| 401 || Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to create companies.
 +
|-
 +
| 405 || Method Not Allowed – A method other than POST was used.
 +
|-
 +
| 500 || Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.
 +
|}
 +
 
 +
'''200 validation response examples:'''
 +
<pre>
 +
{
 +
  "results": {},
 +
  "errors": [
 +
    {"name": "required field"}
 +
  ],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
<pre>
 +
{
 +
  "results": {},
 +
  "errors": [
 +
    {"name": "Unable to create company"}
 +
  ],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
'''401 response body example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Invalid API Key"],
 +
  "code": 401
 +
}
 +
</pre>
 +
 
 +
'''405 response body example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Method not allowed"],
 +
  "code": 405
 +
}
 +
</pre>

Latest revision as of 14:23, 17 July 2026

API » Create Companies

Base URL

https://app.callproof.com

Endpoint

/api/companies/new/

Purpose

Creates a new contact company (account/company record) in your CallProof company. Use this to add a company name that contacts can later be associated with.

HTTP Method

POST

Headers

Header Required Description
Content-Type Yes Must be application/json.

Security

  • Yes – Requires a valid API key and secret with permission to create companies. Credentials are sent in the request body.

Parameters

Path Parameters

None.

Query Parameters

None.

Request Body

Parameter Type Required Description
api_key object Yes Authentication credentials object.
api_key.key string Yes Public API key assigned to your CallProof account.
api_key.secret string Yes Private API secret paired with the API key.
companies object Yes Company creation payload.
companies.name string Yes Name of the company to create. Cannot be empty.

cURL Example

curl -X POST "https://app.callproof.com/api/companies/new/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "companies": {
      "name": "Acme Corp"
    }
  }'

Successful Response (200)

Indicates the company was created successfully. The response returns the new company details.

Field Type Description
results object Newly created company details.
results.id integer Unique identifier for the company.
results.primary_contact integer or string Primary contact identifier associated with the company, or empty if none is set.
results.name string Company name.
results.updated string Date and time the company was last updated (YYYY-MM-DD HH:MM:SS).
results.created string Date and time the company was created (YYYY-MM-DD HH:MM:SS).
errors array Empty list when the request succeeds.
code integer HTTP-style status value; 200 on success.

Example response: 

{
  "results": {
    "id": 321,
    "primary_contact": "",
    "name": "Acme Corp",
    "updated": "2024-06-15 14:30:00",
    "created": "2024-06-15 14:30:00"
  },
  "errors": [],
  "code": 200
}

Notes

  • Only the company name is required to create a company record.
  • A newly created company typically has no primary contact until one is assigned later.
  • This creates a contact company/account record within your CallProof company, not a new CallProof tenant.
  • Field-level validation failures typically return HTTP 200 with details in the errors array and an empty results object.
  • To update an existing company, use /api/companies/update/.

Error Responses

Status Code Meaning
200 Validation issue – The company name is missing/empty, or the company could not be created. Details are provided in the errors array.
401 Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to create companies.
405 Method Not Allowed – A method other than POST was used.
500 Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.

200 validation response examples: 

{
  "results": {},
  "errors": [
    {"name": "required field"}
  ],
  "code": 200
}

{
  "results": {},
  "errors": [
    {"name": "Unable to create company"}
  ],
  "code": 200
}

401 response body example: 

{
  "results": [],
  "errors": ["Invalid API Key"],
  "code": 401
}

405 response body example: 

{
  "results": [],
  "errors": ["Method not allowed"],
  "code": 405
}
Retrieved from "http://docs.callproof.com/index.php?title=API:Companies:Create&oldid=2337"