Difference between revisions of "API:Ping"

From docs
Jump to: navigation, search
 
Line 1: Line 1:
−
 
 
== [[API]] » API Ping ==
 
== [[API]] » API Ping ==
  
−
No Swagger file is in this repo; the Ping docs below are from the live API routes and behavior.
+
The '''API Ping''' endpoint verifies that the CallProof API is reachable and that the provided API credentials are valid. It is recommended as the first API call when testing connectivity or troubleshooting authentication issues.
−
 
 
−
== API Health Check (Ping) ==
 
  
 
=== Base URL ===
 
=== Base URL ===
−
https://app.callproof.com
+
<code>https://app.callproof.com</code>
  
 
=== Endpoint ===
 
=== Endpoint ===
−
/api/ping/
+
<code>/api/ping/</code>
  
 
=== Purpose ===
 
=== Purpose ===
−
Confirms that the CallProof API is reachable and that the supplied API credentials are valid. Use this to verify connectivity and authentication before calling other API operations.
+
Use this endpoint to confirm:
 +
 
 +
* The CallProof API is available.
 +
* Your API Key and Secret are valid.
 +
* Authentication is working correctly before calling other API endpoints.
  
 
=== HTTP Method ===
 
=== HTTP Method ===
−
GET
+
<code>GET</code>
  
 
=== Headers ===
 
=== Headers ===
−
No required headers.
 
  
 
{| class="wikitable"
 
{| class="wikitable"
−
! Header !! Required !! Description
+
! Header
 +
! Required
 +
! Description
 
|-
 
|-
−
| — || — || No headers are required for this endpoint. Authentication is provided via query parameters.
+
| None
 +
| No
 +
| This endpoint does not require HTTP headers. Authentication is provided using query parameters.
 
|}
 
|}
  
 
=== Security ===
 
=== Security ===
−
* '''Yes''' – Requires a valid API key and secret (passed as query parameters).
+
 
 +
* Authentication is required.
 +
* Pass the API credentials using the <code>key</code> and <code>secret</code> query parameters.
  
 
=== Parameters ===
 
=== Parameters ===
  
 
==== Query Parameters ====
 
==== Query Parameters ====
 +
 
{| class="wikitable"
 
{| class="wikitable"
−
! Parameter !! Type !! Required !! Description
+
! Parameter
 +
! Type
 +
! Required
 +
! Description
 
|-
 
|-
−
| key || string || Yes || Public API key assigned to your CallProof account.
+
| key
 +
| string
 +
| Yes
 +
| Public API key assigned to your CallProof account.
 
|-
 
|-
−
| secret || string || Yes || Private API secret paired with the API key.
+
| secret
 +
| string
 +
| Yes
 +
| Private API secret associated with the API key.
 
|}
 
|}
  
 
==== Path Parameters ====
 
==== Path Parameters ====
 +
 
None.
 
None.
  
 
==== Request Body ====
 
==== Request Body ====
 +
 
None.
 
None.
  
−
=== cURL Example ===
+
=== Example Request ===
 +
 
 +
==== cURL ====
 +
 
 
<pre>
 
<pre>
 
curl -X GET "https://app.callproof.com/api/ping/?key=YOUR_API_KEY&secret=YOUR_API_SECRET"
 
curl -X GET "https://app.callproof.com/api/ping/?key=YOUR_API_KEY&secret=YOUR_API_SECRET"
Line 53: Line 74:
  
 
=== Successful Response (200) ===
 
=== Successful Response (200) ===
−
Indicates the API is available and the provided credentials were accepted.
+
 
 +
Returns a successful response when the API is available and the supplied credentials are valid.
  
 
{| class="wikitable"
 
{| class="wikitable"
−
! Field !! Type !! Description
+
! Field
 +
! Type
 +
! Description
 
|-
 
|-
−
| result || object || Outcome of the health check.
+
| result
 +
| object
 +
| Contains the result of the health check.
 
|-
 
|-
−
| result.result || integer || Value of <code>1</code> indicates a successful ping.
+
| result.result
 +
| integer
 +
| A value of <code>1</code> indicates the API ping was successful.
 
|-
 
|-
−
| errors || array || Empty list when the request succeeds.
+
| errors
 +
| array
 +
| Empty when no errors occur.
 
|-
 
|-
−
| code || integer || HTTP-style status value; <code>200</code> on success.
+
| code
 +
| integer
 +
| HTTP status code returned by the API.
 
|}
 
|}
  
−
Example response:
+
==== Example Response ====
 +
 
 
<pre>
 
<pre>
 
{
 
{
−
  "result": {
+
    "result": {
−
    "result": 1
+
        "result": 1
−
  },
+
    },
−
  "errors": [],
+
    "errors": [],
−
  "code": 200
+
    "code": 200
 
}
 
}
 
</pre>
 
</pre>
  
 
=== Error Responses ===
 
=== Error Responses ===
 +
 
{| class="wikitable"
 
{| class="wikitable"
−
! Status Code !! Meaning
+
! HTTP Status
 +
! Description
 
|-
 
|-
−
| 401 || Unauthorized – The API key and/or secret is missing, invalid, inactive, or associated with a disabled account.
+
| 401
 +
| Unauthorized. The API Key or Secret is missing, invalid, inactive, or belongs to a disabled account.
 
|-
 
|-
−
| 405 || Method Not Allowed – A method other than GET was used.
+
| 405
 +
| Method Not Allowed. Only the <code>GET</code> method is supported.
 
|-
 
|-
−
| 500 || Internal Server Error – An unexpected server problem occurred. Not specified in Swagger.
+
| 500
 +
| Internal Server Error. An unexpected server error occurred.
 
|}
 
|}
  
−
'''401 response body example:'''
+
==== 401 Unauthorized ====
 +
 
 
<pre>
 
<pre>
 
{
 
{
−
  "results": [],
+
    "results": [],
−
  "errors": ["Invalid API Key"],
+
    "errors": [
−
  "code": 401
+
        "Invalid API Key"
 +
    ],
 +
    "code": 401
 
}
 
}
 
</pre>
 
</pre>
  
−
'''405 response body example:'''
+
==== 405 Method Not Allowed ====
 +
 
 
<pre>
 
<pre>
 
{
 
{
−
  "results": [],
+
    "results": [],
−
  "errors": ["Method not allowed"],
+
    "errors": [
−
  "code": 405
+
        "Method not allowed"
 +
    ],
 +
    "code": 405
 
}
 
}
 
</pre>
 
</pre>
  
−
---
+
=== Notes ===
  
−
**Note:** This API uses query-parameter credentials (`key` / `secret`), not Bearer token headers. Say when you want the next endpoint documented.
+
* Authentication credentials must be supplied as the <code>key</code> and <code>secret</code> query parameters.
 +
* This endpoint does '''not''' support Bearer Token authentication.
 +
* Use this endpoint to verify connectivity and authentication before calling other CallProof API endpoints.
 +
* No request body or custom HTTP headers are required.

Latest revision as of 07:27, 17 July 2026

API » API Ping

The API Ping endpoint verifies that the CallProof API is reachable and that the provided API credentials are valid. It is recommended as the first API call when testing connectivity or troubleshooting authentication issues.

Base URL

https://app.callproof.com

Endpoint

/api/ping/

Purpose

Use this endpoint to confirm:

  • The CallProof API is available.
  • Your API Key and Secret are valid.
  • Authentication is working correctly before calling other API endpoints.

HTTP Method

GET

Headers

Header Required Description
None No This endpoint does not require HTTP headers. Authentication is provided using query parameters.

Security

  • Authentication is required.
  • Pass the API credentials using the key and secret query parameters.

Parameters

Query Parameters

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

Path Parameters

None.

Request Body

None.

Example Request

cURL

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

Successful Response (200)

Returns a successful response when the API is available and the supplied credentials are valid.

Field Type Description
result object Contains the result of the health check.
result.result integer A value of 1 indicates the API ping was successful.
errors array Empty when no errors occur.
code integer HTTP status code returned by the API.

Example Response

{
    "result": {
        "result": 1
    },
    "errors": [],
    "code": 200
}

Error Responses

HTTP Status Description
401 Unauthorized. The API Key or Secret is missing, invalid, inactive, or belongs to a disabled account.
405 Method Not Allowed. Only the GET method is supported.
500 Internal Server Error. An unexpected server error occurred.

401 Unauthorized

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

405 Method Not Allowed

{
    "results": [],
    "errors": [
        "Method not allowed"
    ],
    "code": 405
}

Notes

  • Authentication credentials must be supplied as the key and secret query parameters.
  • This endpoint does not support Bearer Token authentication.
  • Use this endpoint to verify connectivity and authentication before calling other CallProof API endpoints.
  • No request body or custom HTTP headers are required.
Retrieved from "http://docs.callproof.com/index.php?title=API:Ping&oldid=2080"