Difference between revisions of "API:Companies:Delete"

From docs
Jump to: navigation, search
(Created page with "== API » Delete Companies == '''URL:''' <nowiki>https://app.callproof.com/api/companies/delete/</nowiki> '''Method:''' POST '''Required Fields:''' * '''''api_key[...")
 
 
Line 1: Line 1:
 
== [[API]] &#187; Delete Companies ==
 
== [[API]] &#187; Delete Companies ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/companies/delete/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' POST
+
=== Endpoint ===
 +
/api/companies/delete/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Permanently removes a contact company (account/company record) from your CallProof company. Use this when a company record should no longer be retained. The authenticated user must also have permission to delete contacts/companies.
  
−
* '''''api_key[key]''''' - API Key
+
=== HTTP Method ===
−
* '''''api_key[secret]''''' - API Key Secret
+
POST
−
* '''''companies[id]''''' - Companies id
 
  
−
'''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. The authenticated user must also have delete permission for contacts/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 deletion payload.
 +
|-
 +
| companies.id || integer || Yes || Unique identifier of the company to delete. Must belong to your company.
 +
|}
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/companies/delete/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "companies": {
 +
      "id": 321
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Indicates the company was successfully deleted. The response returns the details of the deleted company.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || object || Details of the deleted company.
 +
|-
 +
| results.id || integer || Unique identifier of the deleted company.
 +
|-
 +
| results.primary_contact || integer or string || Primary contact identifier that was associated with the company, or empty if none was 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 Corp",
 +
    "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.
 +
* This action permanently deletes the company record and cannot be undone through this endpoint.
 +
* The authenticated user must have delete permission for contacts/companies in addition to valid API credentials.
 +
* The response returns the deleted company’s details for confirmation.
 +
* Deleting a company record may affect related contacts associated with that company. Not specified in Swagger.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 400 || Bad Request – The user lacks delete permission, the JSON payload is invalid, the company ID is missing, or the company was not found.
 +
|-
 +
| 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.
 +
|}
 +
 
 +
'''400 response body examples:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Permission denied to delete companies"],
 +
  "code": 400
 +
}
 +
</pre>
 +
 
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Id required"],
 +
  "code": 400
 +
}
 +
</pre>
 +
 
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Account not found."],
 +
  "code": 400
 +
}
 +
</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:27, 17 July 2026

API » Delete Companies

Base URL

https://app.callproof.com

Endpoint

/api/companies/delete/

Purpose

Permanently removes a contact company (account/company record) from your CallProof company. Use this when a company record should no longer be retained. The authenticated user must also have permission to delete contacts/companies.

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. The authenticated user must also have delete permission for contacts/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 deletion payload.
companies.id integer Yes Unique identifier of the company to delete. Must belong to your company.

cURL Example

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

Successful Response (200)

Indicates the company was successfully deleted. The response returns the details of the deleted company.

Field Type Description
results object Details of the deleted company.
results.id integer Unique identifier of the deleted company.
results.primary_contact integer or string Primary contact identifier that was associated with the company, or empty if none was 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 Corp",
    "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.
  • This action permanently deletes the company record and cannot be undone through this endpoint.
  • The authenticated user must have delete permission for contacts/companies in addition to valid API credentials.
  • The response returns the deleted company’s details for confirmation.
  • Deleting a company record may affect related contacts associated with that company. Not specified in Swagger.

Error Responses

Status Code Meaning
400 Bad Request – The user lacks delete permission, the JSON payload is invalid, the company ID is missing, or the company was not found.
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.

400 response body examples: 

{
  "results": [],
  "errors": ["Permission denied to delete companies"],
  "code": 400
}

{
  "results": [],
  "errors": ["Id required"],
  "code": 400
}

{
  "results": [],
  "errors": ["Account not found."],
  "code": 400
}

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:Delete&oldid=2339"