Difference between revisions of "API:Opportunity:Create"

From docs
Jump to: navigation, search
(Created page with "== API » Create Opportunity == '''URL:''' <nowiki>https://app.callproof.com/api/opportunity/new/</nowiki> '''Method:''' POST '''Required Fields:''' * '''''api_key...")
 
 
(One intermediate revision by one other user not shown)
Line 1: Line 1:
 
== [[API]] &#187; Create Opportunity ==
 
== [[API]] &#187; Create Opportunity ==
  
−
'''URL:''' <nowiki>https://app.callproof.com/api/opportunity/new/</nowiki>
+
=== Base URL ===
 +
https://app.callproof.com
  
−
'''Method:''' POST
+
=== Endpoint ===
 +
/api/opportunity/new/
  
−
'''Required Fields:'''
+
=== Purpose ===
 +
Creates a new sales opportunity in your CallProof company. Use this to record an opportunity against a primary contact, including type, stage, value, probability, close date, notes, and optional additional related contacts.
  
−
* '''''api_key[key]''''' - API Key
+
=== HTTP Method ===
−
* '''''api_key[secret]''''' - API Key Secret
+
POST
−
* '''''opportunity[opp_name]''''' - Opportunity name
 
−
* '''''opportunity[opp_stage_id]''''' - Opportunity Stage ID
 
−
* '''''opportunity[opp_type_id]''''' - Opportunity Stage ID
 
−
* '''''opportunity[close_date]''''' - Opportunity Close Date MM-DD-YYYY
 
−
* '''''opportunity[notes]''''' - Notes for opportunity
 
−
* '''''opportunity[contact_id]''''' - Contact
 
−
* '''''opportunity[value]''''' - Value
 
−
* '''''opportunity[probability]''''' - Probability (1-100)
 
−
* '''''opportunity[contact_ids]''''' - Array of other contact ids to add in the opportunity
 
  
 +
=== Headers ===
 +
{| class="wikitable"
 +
! Header !! Required !! Description
 +
|-
 +
| Content-Type || Yes || Must be <code>application/json</code>.
 +
|}
  
−
'''Data Returned:'''
+
=== Security ===
 +
* '''Yes''' – Requires a valid API key and secret with permission to create opportunities. Credentials are sent in the request body.
  
−
* '''''results''''' - Companies details
+
=== Parameters ===
−
* '''''errors''''' - Array of errors produced by the request
+
 
−
* '''''code''''' - HTTP request status
+
==== 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.
 +
|-
 +
| opportunity || object || Yes || Opportunity creation payload.
 +
|-
 +
| opportunity.contact_id || integer || Yes || Unique identifier of the primary contact for the opportunity. Must belong to your company.
 +
|-
 +
| opportunity.opp_type_id || integer || Yes || Opportunity type identifier. Must match a type in your company.
 +
|-
 +
| opportunity.opp_stage_id || integer || Yes || Opportunity stage identifier. Must match a stage in your company.
 +
|-
 +
| opportunity.close_date || datetime string || Yes || Expected or planned close date for the opportunity.
 +
|-
 +
| opportunity.opp_name || string || No || Opportunity name.
 +
|-
 +
| opportunity.notes || string || No || Opportunity notes. Maximum 1,024 characters.
 +
|-
 +
| opportunity.probability || integer || No || Win probability percentage from 0 to 100. Defaults to <code>0</code> if omitted or invalid. Values below 0 are set to 0; values above 100 are set to 100.
 +
|-
 +
| opportunity.value || number || No || Opportunity value. Defaults to <code>1</code> if omitted, invalid, or less than 1. Maximum allowed value is <code>1000000</code>.
 +
|-
 +
| opportunity.rep_id || integer || No || User ID of the sales representative to assign. Applied only when the authenticated API user is a manager. Otherwise the authenticated user is assigned.
 +
|-
 +
| opportunity.contact_ids || array of integers || No || Additional contact IDs to associate with the opportunity. The primary contact is excluded if included again.
 +
|}
 +
 
 +
=== cURL Example ===
 +
<pre>
 +
curl -X POST "https://app.callproof.com/api/opportunity/new/" \
 +
  -H "Content-Type: application/json" \
 +
  -d '{
 +
    "api_key": {
 +
      "key": "YOUR_API_KEY",
 +
      "secret": "YOUR_API_SECRET"
 +
    },
 +
    "opportunity": {
 +
      "contact_id": 789,
 +
      "opp_type_id": 1,
 +
      "opp_stage_id": 2,
 +
      "opp_name": "Annual Renewal",
 +
      "value": 25000,
 +
      "probability": 50,
 +
      "close_date": "2024-12-31",
 +
      "notes": "Discussing renewal terms",
 +
      "contact_ids": [790]
 +
    }
 +
  }'
 +
</pre>
 +
 
 +
=== Successful Response (200) ===
 +
Indicates the opportunity was created successfully. The response returns the new opportunity details.
 +
 
 +
{| class="wikitable"
 +
! Field !! Type !! Description
 +
|-
 +
| results || object || Newly created opportunity details.
 +
|-
 +
| results.opp_id || integer || Unique identifier for the opportunity.
 +
|-
 +
| results.rep || object || Sales representative associated with the opportunity.
 +
|-
 +
| results.contact_name || string || Display name of the primary contact.
 +
|-
 +
| results.contact_id || integer || Identifier of the primary contact.
 +
|-
 +
| results.opp_type_id || integer || Opportunity type identifier.
 +
|-
 +
| results.opp_stage_id || integer || Opportunity stage identifier.
 +
|-
 +
| results.opp_name || string || Opportunity name.
 +
|-
 +
| results.value || string || Opportunity value.
 +
|-
 +
| results.probability || string || Win probability percentage.
 +
|-
 +
| results.derived || string || Derived value calculated from value and probability.
 +
|-
 +
| results.created || string || Date and time the opportunity was created (<code>YYYY-MM-DD HH:MM:SS</code>).
 +
|-
 +
| results.updated || string || Date and time the opportunity was last updated (<code>YYYY-MM-DD HH:MM:SS</code>).
 +
|-
 +
| results.close_date || string || Close date value returned for the opportunity.
 +
|-
 +
| results.other_contacts || array || Additional contacts associated with the opportunity.
 +
|-
 +
| results.other_contacts[].id || integer || Additional contact identifier.
 +
|-
 +
| results.other_contacts[].name || string || Additional contact display name.
 +
|-
 +
| results.notes || string || Opportunity notes.
 +
|-
 +
| errors || object || Empty object when the request succeeds.
 +
|-
 +
| code || integer || HTTP-style status value; <code>200</code> on success.
 +
|}
 +
 
 +
Example response:
 +
<pre>
 +
{
 +
  "results": {
 +
    "opp_id": 9001,
 +
    "rep": {
 +
      "id": 123,
 +
      "email": "rep@example.com",
 +
      "user_id": 456,
 +
      "name": "Jane Smith",
 +
      "title": "Account Executive",
 +
      "updated": "2024-06-01 10:00:00"
 +
    },
 +
    "contact_name": "John Doe",
 +
    "contact_id": 789,
 +
    "opp_type_id": 1,
 +
    "opp_stage_id": 2,
 +
    "opp_name": "Annual Renewal",
 +
    "value": "25000.0",
 +
    "probability": "50",
 +
    "derived": "12500.0",
 +
    "created": "2024-06-15 14:30:00",
 +
    "updated": "2024-06-15 14:30:00",
 +
    "close_date": "2024-06-15 14:30:00",
 +
    "other_contacts": [
 +
      {
 +
        "id": 790,
 +
        "name": "Sarah Jones"
 +
      }
 +
    ],
 +
    "notes": "Discussing renewal terms"
 +
  },
 +
  "errors": {},
 +
  "code": 200
 +
}
 +
</pre>
 +
 
 +
=== Notes ===
 +
* Required fields are <code>contact_id</code>, <code>opp_type_id</code>, <code>opp_stage_id</code>, and <code>close_date</code>.
 +
* The primary contact, opportunity type, and opportunity stage must belong to your company.
 +
* Probability is constrained to the range 0–100.
 +
* Opportunity value is constrained to the range 1–1,000,000.
 +
* Non-manager users are always assigned as the opportunity owner; managers may assign another sales representative via <code>rep_id</code>.
 +
* Additional contacts in <code>contact_ids</code> are associated with the opportunity when valid.
 +
* Field-level validation failures typically return HTTP <code>200</code> with details in the <code>errors</code> object and an empty <code>results</code> object.
 +
* Invalid JSON in the request body returns HTTP <code>400</code>.
 +
* Use <code>/api/opportunity/stages/get/</code> and <code>/api/opportunity/type/get/</code> to obtain valid stage and type IDs.
 +
 
 +
=== Error Responses ===
 +
{| class="wikitable"
 +
! Status Code !! Meaning
 +
|-
 +
| 200 || Validation issue – One or more required fields are missing or invalid. Details are provided in the <code>errors</code> object.
 +
|-
 +
| 400 || Bad Request – The JSON payload is invalid or required opportunity data is missing.
 +
|-
 +
| 401 || Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to create opportunities.
 +
|-
 +
| 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 example:'''
 +
<pre>
 +
{
 +
  "results": [],
 +
  "errors": ["Invalid json"],
 +
  "code": 400
 +
}
 +
</pre>
 +
 
 +
'''200 validation response example:'''
 +
<pre>
 +
{
 +
  "results": {},
 +
  "errors": {
 +
    "contact_id": "required field",
 +
    "opp_type_id": "required field",
 +
    "opp_stage_id": "required field",
 +
    "close_date": "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:45, 17 July 2026

API » Create Opportunity

Base URL

https://app.callproof.com

Endpoint

/api/opportunity/new/

Purpose

Creates a new sales opportunity in your CallProof company. Use this to record an opportunity against a primary contact, including type, stage, value, probability, close date, notes, and optional additional related contacts.

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 opportunities. 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.
opportunity object Yes Opportunity creation payload.
opportunity.contact_id integer Yes Unique identifier of the primary contact for the opportunity. Must belong to your company.
opportunity.opp_type_id integer Yes Opportunity type identifier. Must match a type in your company.
opportunity.opp_stage_id integer Yes Opportunity stage identifier. Must match a stage in your company.
opportunity.close_date datetime string Yes Expected or planned close date for the opportunity.
opportunity.opp_name string No Opportunity name.
opportunity.notes string No Opportunity notes. Maximum 1,024 characters.
opportunity.probability integer No Win probability percentage from 0 to 100. Defaults to 0 if omitted or invalid. Values below 0 are set to 0; values above 100 are set to 100.
opportunity.value number No Opportunity value. Defaults to 1 if omitted, invalid, or less than 1. Maximum allowed value is 1000000.
opportunity.rep_id integer No User ID of the sales representative to assign. Applied only when the authenticated API user is a manager. Otherwise the authenticated user is assigned.
opportunity.contact_ids array of integers No Additional contact IDs to associate with the opportunity. The primary contact is excluded if included again.

cURL Example

curl -X POST "https://app.callproof.com/api/opportunity/new/" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": {
      "key": "YOUR_API_KEY",
      "secret": "YOUR_API_SECRET"
    },
    "opportunity": {
      "contact_id": 789,
      "opp_type_id": 1,
      "opp_stage_id": 2,
      "opp_name": "Annual Renewal",
      "value": 25000,
      "probability": 50,
      "close_date": "2024-12-31",
      "notes": "Discussing renewal terms",
      "contact_ids": [790]
    }
  }'

Successful Response (200)

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

Field Type Description
results object Newly created opportunity details.
results.opp_id integer Unique identifier for the opportunity.
results.rep object Sales representative associated with the opportunity.
results.contact_name string Display name of the primary contact.
results.contact_id integer Identifier of the primary contact.
results.opp_type_id integer Opportunity type identifier.
results.opp_stage_id integer Opportunity stage identifier.
results.opp_name string Opportunity name.
results.value string Opportunity value.
results.probability string Win probability percentage.
results.derived string Derived value calculated from value and probability.
results.created string Date and time the opportunity was created (YYYY-MM-DD HH:MM:SS).
results.updated string Date and time the opportunity was last updated (YYYY-MM-DD HH:MM:SS).
results.close_date string Close date value returned for the opportunity.
results.other_contacts array Additional contacts associated with the opportunity.
results.other_contacts[].id integer Additional contact identifier.
results.other_contacts[].name string Additional contact display name.
results.notes string Opportunity notes.
errors object Empty object when the request succeeds.
code integer HTTP-style status value; 200 on success.

Example response: 

{
  "results": {
    "opp_id": 9001,
    "rep": {
      "id": 123,
      "email": "rep@example.com",
      "user_id": 456,
      "name": "Jane Smith",
      "title": "Account Executive",
      "updated": "2024-06-01 10:00:00"
    },
    "contact_name": "John Doe",
    "contact_id": 789,
    "opp_type_id": 1,
    "opp_stage_id": 2,
    "opp_name": "Annual Renewal",
    "value": "25000.0",
    "probability": "50",
    "derived": "12500.0",
    "created": "2024-06-15 14:30:00",
    "updated": "2024-06-15 14:30:00",
    "close_date": "2024-06-15 14:30:00",
    "other_contacts": [
      {
        "id": 790,
        "name": "Sarah Jones"
      }
    ],
    "notes": "Discussing renewal terms"
  },
  "errors": {},
  "code": 200
}

Notes

  • Required fields are contact_id, opp_type_id, opp_stage_id, and close_date.
  • The primary contact, opportunity type, and opportunity stage must belong to your company.
  • Probability is constrained to the range 0–100.
  • Opportunity value is constrained to the range 1–1,000,000.
  • Non-manager users are always assigned as the opportunity owner; managers may assign another sales representative via rep_id.
  • Additional contacts in contact_ids are associated with the opportunity when valid.
  • Field-level validation failures typically return HTTP 200 with details in the errors object and an empty results object.
  • Invalid JSON in the request body returns HTTP 400.
  • Use /api/opportunity/stages/get/ and /api/opportunity/type/get/ to obtain valid stage and type IDs.

Error Responses

Status Code Meaning
200 Validation issue – One or more required fields are missing or invalid. Details are provided in the errors object.
400 Bad Request – The JSON payload is invalid or required opportunity data is missing.
401 Unauthorized – The API key and/or secret is missing, invalid, inactive, associated with a disabled account, or lacks permission to create opportunities.
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 example: 

{
  "results": [],
  "errors": ["Invalid json"],
  "code": 400
}

200 validation response example: 

{
  "results": {},
  "errors": {
    "contact_id": "required field",
    "opp_type_id": "required field",
    "opp_stage_id": "required field",
    "close_date": "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:Opportunity:Create&oldid=2347"