Difference between revisions of "API:People:Roles:Get"

From docs
Jump to: navigation, search
 
Line 1: Line 1:
 
== [[API]] » Get People Roles ==
 
== [[API]] » Get People Roles ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/contact/people/roles/get/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' GET
+
=== Endpoint ===
 +
/api/contact/people/roles/get/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Retrieves the available people roles configured for your CallProof company. Use this to obtain role options that can be assigned when creating or managing contact personnel.
  
−
* '''''key''''' - API Key
+
=== HTTP Method ===
−
* '''''secret''''' - API Key Secret
+
GET
  
−
'''Optional Fields:'''
+
=== Headers ===
 +
No required headers.
  
−
None
+
{| class="wikitable"
 +
! Header !! Required !! Description
 +
|-
 +
| — || — || No headers are required for this endpoint. Authentication is provided via query parameters.
 +
|}
  
−
'''Data Returned:'''
+
=== Security ===
 +
* '''Yes''' – Requires a valid API key and secret with permission to read contacts.
  
−
* '''''results''''' - Details of roles
+
=== Parameters ===
−
* '''''errors''''' - Array of errors produced by the request
+
 
−
* '''''code''''' - HTTP request status
+
==== Path Parameters ====
 +
None.
 +
 
 +
==== Query Parameters ====
 +
{| class="wikitable"
 +
! Parameter !! Type !! Required !! Description
 +
|-
 +
| key || string || Yes || Public API key assigned to your CallProof account.
 +
|-
 +
| secret || string || Yes || Private API secret paired with the API key.
 +
|}
 +
 
 +
==== Request Body ====
 +
None.
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X GET "https://app.callproof.com/api/contact/people/roles/get/?key=YOUR_API_KEY&secret=YOUR_API_SECRET"
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Returns the people roles available for your company.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || array || List of people roles configured for your company.
 +
|-
 +
| results[].id || integer || Unique identifier for the role.
 +
|-
 +
| results[].name || string || Display name of the role.
 +
|-
 +
| errors || array || Empty list when the request succeeds.
 +
|-
 +
| code || integer || HTTP-style status value; <code>200</code> on success.
 +
|}
 +
 
 +
Example response:
 +
<pre>
 +
{
 +
  "results": [
 +
    {
 +
      "id": 3,
 +
      "name": "Decision Maker"
 +
    },
 +
    {
 +
      "id": 4,
 +
      "name": "Influencer"
 +
    }
 +
  ],
 +
  "errors": [],
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Notes ===
 +
* Returns only people roles belonging to your company.
 +
* If no roles are configured, the response returns an empty <code>results</code> list with status <code>200</code>.
 +
* Role IDs from this endpoint can be used when creating personnel via <code>/api/contact/personnel/create/</code>.
 +
* This endpoint does not support pagination or filtering.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 401 || Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to read contacts.
 +
|-
 +
| 405 || Method Not Allowed – A method other than GET was used.
 +
|-
 +
| 500 || Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.
 +
|}
 +
 
 +
'''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 12:29, 17 July 2026

API » Get People Roles

Base URL

https://app.callproof.com

Endpoint

/api/contact/people/roles/get/

Purpose

Retrieves the available people roles configured for your CallProof company. Use this to obtain role options that can be assigned when creating or managing contact personnel.

HTTP Method

GET

Headers

No required headers.

Header Required Description
— — No headers are required for this endpoint. Authentication is provided via query parameters.

Security

  • Yes – Requires a valid API key and secret with permission to read contacts.

Parameters

Path Parameters

None.

Query Parameters

Parameter Type Required Description
key string Yes Public API key assigned to your CallProof account.
secret string Yes Private API secret paired with the API key.

Request Body

None.

cURL Example

curl -X GET "https://app.callproof.com/api/contact/people/roles/get/?key=YOUR_API_KEY&secret=YOUR_API_SECRET"

Successful Response (200)

Returns the people roles available for your company.

Field Type Description
results array List of people roles configured for your company.
results[].id integer Unique identifier for the role.
results[].name string Display name of the role.
errors array Empty list when the request succeeds.
code integer HTTP-style status value; 200 on success.

Example response: 

{
  "results": [
    {
      "id": 3,
      "name": "Decision Maker"
    },
    {
      "id": 4,
      "name": "Influencer"
    }
  ],
  "errors": [],
  "code": 200
}

Notes

  • Returns only people roles belonging to your company.
  • If no roles are configured, the response returns an empty results list with status 200.
  • Role IDs from this endpoint can be used when creating personnel via /api/contact/personnel/create/.
  • This endpoint does not support pagination or filtering.

Error Responses

Status Code Meaning
401 Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to read contacts.
405 Method Not Allowed – A method other than GET was used.
500 Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.

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:People:Roles:Get&oldid=2295"