API:Opportunity:Create

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
}