Difference between revisions of "API:Companies:Update"

From docs
Jump to: navigation, search
(Created page with "== API » Update Companies == '''URL:''' <nowiki>https://app.callproof.com/api/companies/update/</nowiki> '''Method:''' POST '''Required Fields:''' * '''''api_key[...")
 
 
Line 1: Line 1:
 
== [[API]] &#187; Update Companies ==
 
== [[API]] &#187; Update Companies ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/companies/update/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' POST
+
=== Endpoint ===
 +
/api/companies/update/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Updates an existing contact company (account/company record) in your CallProof company. Use this to change the company name or set the primary contact for the company.
  
−
* '''''api_key[key]''''' - API Key
+
=== HTTP Method ===
−
* '''''api_key[secret]''''' - API Key Secret
+
POST
−
* '''''companies[id]''''' - Companies id
 
−
* '''''companies[name]''''' - Companies name
 
−
* '''''companies[primary_contact]''''' - Contact id belongs to companies
 
  
−
'''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 update 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 update payload.
 +
|-
 +
| companies.id || integer || Yes || Unique identifier of the company to update. Must belong to your company.
 +
|-
 +
| companies.name || string || Yes || Updated company name. Cannot be empty.
 +
|-
 +
| companies.primary_contact || integer || No || Identifier of the contact to set as the company’s primary contact. The contact must belong to your company and be associated with this company.
 +
|}
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/companies/update/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "companies": {
 +
      "id": 321,
 +
      "name": "Acme Corporation",
 +
      "primary_contact": 789
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Indicates the company was updated successfully. The response returns the updated company details.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || object || Updated 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": 789,
 +
    "name": "Acme Corporation",
 +
    "updated": "2024-06-15 14:35:00",
 +
    "created": "2024-01-10 09:00:00"
 +
  },
 +
  "errors": [],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Notes ===
 +
* The company ID must belong to your company.
 +
* The company name is required and cannot be empty.
 +
* <code>primary_contact</code> is applied only when it references a contact that belongs to your company and is associated with this company; otherwise the primary contact may be cleared.
 +
* This updates a contact company/account record within your CallProof company, not a 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 create a new company, use <code>/api/companies/new/</code>.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 200 || Validation issue – The company ID and/or name is missing or invalid, or the company could not be updated. 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 update 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": [
 +
    {"id": "required"},
 +
    {"name": "required field"}
 +
  ],
 +
  "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:25, 17 July 2026

API » Update Companies

Base URL

https://app.callproof.com

Endpoint

/api/companies/update/

Purpose

Updates an existing contact company (account/company record) in your CallProof company. Use this to change the company name or set the primary contact for the company.

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 update 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 update payload.
companies.id integer Yes Unique identifier of the company to update. Must belong to your company.
companies.name string Yes Updated company name. Cannot be empty.
companies.primary_contact integer No Identifier of the contact to set as the company’s primary contact. The contact must belong to your company and be associated with this company.

cURL Example

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

Successful Response (200)

Indicates the company was updated successfully. The response returns the updated company details.

Field Type Description
results object Updated 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": 789,
    "name": "Acme Corporation",
    "updated": "2024-06-15 14:35:00",
    "created": "2024-01-10 09:00:00"
  },
  "errors": [],
  "code": 200
}

Notes

  • The company ID must belong to your company.
  • The company name is required and cannot be empty.
  • primary_contact is applied only when it references a contact that belongs to your company and is associated with this company; otherwise the primary contact may be cleared.
  • This updates a contact company/account record within your CallProof company, not a CallProof tenant.
  • Field-level validation failures typically return HTTP 200 with details in the errors array and an empty results object.
  • To create a new company, use /api/companies/new/.

Error Responses

Status Code Meaning
200 Validation issue – The company ID and/or name is missing or invalid, or the company could not be updated. 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 update 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": [
    {"id": "required"},
    {"name": "required field"}
  ],
  "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:Update&oldid=2338"