Capture Opportunities
Captures leads and opportunities in your LeadSquared account.
Lead Create/Update
- You must pass at least 1 unique field (attribute-value pair) in the
LeadDetails
object. For example,"Attribute":"EmailAddress",
"Value":"example@leadsquared.com"
- If you don’t pass at least 1 unique field, you’ll receive an error.
- If the unique field(s) you pass are not associated with any lead in the system, a new lead will get created.
Opportunity Create
An opportunity captured activity is always posted on the lead.
- You must pass the correct
OpportunityEventCode
in theOpportunity
object. To find the event code, navigate to My Profile>Settings>Opportunities>Opportunity Types, and under the Code column, copy the event code for the relevant opportunity type.
- The
OpportunityNote
andOpportunityDateTime
parameters are optional. - You may pass the opportunity fields in the
Fields
object as attribute-value pairs. For example,"SchemaName":"mx_Custom_1",
"Value":"1"
Note: You must pass the schema name of the opportunity fields.
Duplicate Detection Rules
If you’ve set up duplicate detection rules in your account –
- If you pass opportunity fields that are not associated with an existing opportunity, a new opportunity is created and an opportunity captured activity is posted on the lead.
- If you pass opportunity fields associated with an existing opportunity (as specified in the duplicate detection rules), a new opportunity will not be created. An opportunity captured activity will be posted on the lead and a duplicate detected activity will also be posted on the lead.
Response Parameters
Parameters |
Description | Values | |
AdditionalDetails | Top-level array of activity details. | ||
ActivityId | Activity Id for the captured opportunity. | caf2201a-ead4-4cd7-8a0e-16791c31d905 | |
PostDeDupActionPerformed | 1 represents a new opportunity has been created.
3 represents a duplicate detected activity has been posted, and no new opportunity has been created. |
1 | |
ConflictedOpportunityId | The Id of the duplicate opportunity that’s been detected. It will return “null” if no duplicate opportunity has been detected. | null | |
CreatedOpportunityId | The Id of the new opportunity that’s been created. It will return “null” if a duplicate opportunity has been detected. | 24590a6c-9dec-4bfd-94df-b7c7d70e0194 | |
ExceptionMessage | The description of the exception. | “A Lead with same Email already exists.” | |
ExceptionType | The type of exception. | “MXDuplicateEntryException” | |
IsUnique | “true” denotes if an opportunity is unique.
“false” denotes if an opportunity is a duplicate. |
true | |
PrimaryAction | 0 represents No Action
1 represents CreateOpportunity 2 represents CreateOpportunityCapturedActivity 3 represents CreateDuplicateDetectedActivity |
1 | |
RelatedProspectId | The lead Id on which the opportunity is posted. | 489c644c-931e-4ed0-bf72-926a2945e72f | |
RequestId | The identifier of the API request. This can be used to track the API call. | 06b09468-5b83-420a-a466-2ca9253b9364 | |
SecondaryAction | 0 represents No Action
1 represents CreateOpportunity 2 represents CreateOpportunityCapturedActivity 3 represents CreateDuplicateDetectedActivity |
2 | |
Status |
0 – Success. If the primary action and secondary action are executed successfully. 2 – PartialSuccess. If the primary action is executed but secondary action is a failure. 1 – Failure. If primary action is not executed successfully. |
0 |
Note:
If you want the API to throw the exceptions for the dependant dropdown fields, reach out to your account manager or write to support@leadsquared.com. Once these exceptions are enabled –
- If a Dropdown Child field is passed in the payload, an exception is thrown if the parent field is not passed.
- If the Dropdown parent and Dropdown Child fields are passed, then an exception is thrown if the combination of the values is incorrect or not according to the options configured.
- Empty values will be allowed in the Dropdown Child if the field is not mandatory.
API URL
Request
Content-Type: application/json{ "LeadDetails":[ { "Attribute":"EmailAddress", "Value":"johndoe4633@example.com" }, { "Attribute":"ProspectID", "Value":"4d03f397-49e7-4e4e-8168-5f51d591c592" }, { "Attribute":"SearchBy", "Value":"ProspectId" }, { "Attribute":"__UseUserDefinedGuid__", "Value":"true" } ], "Opportunity":{ "OpportunityEventCode":12000, "OpportunityNote": "Opportunity capture api overwrite", "UpdateEmptyFields":true, "DoNotPostDuplicateActivity":true, "DoNotChangeOwner":true, "Fields":[ { "SchemaName":"mx_Custom_1", "Value":"Opportunity-Test" }, { "SchemaName":"mx_Custom_2", "Value":"Prospecting" }, { "SchemaName":"mx_Custom_5", "Value":"Prospecting" }, { "SchemaName":"Status", "Value":"Open" } ] } }
Request Parameters
Parameter | Description |
---|---|
LeadDetails | Array containing lead fields. These should be passed as attribute-value pairs.
|
OpportunityEventCode | The opportunity event code. This is a mandatory field. |
OpportunityNote | Notes (text) associated with the opportunity. |
OpportunityDateTime | Opportunity date and time is in the yyyy-mm-dd hh:mm:ss format. |
OverwriteFields | If you pass |
UpdateEmptyFields | If you pass |
DoNotPostDuplicateActivity | If you pass |
DoNotChangeOwner | If you pass |
Fields | Attribute-value pairs for the opportunity fields you want to capture. You must pass the schema names of the opportunity fields. |
Response
{ "AdditionalDetails":[ { "ActivityId":"b7dba235-9217-4705-bcd8-741dcdf32071", "PostDeDupActionPerformed":1 } ], "ConflictedOpportunityId":null, "CreatedOpportunityId":"d5976a98-6731-4b21-908b-90b0d9938b45", "ExceptionMessage":null, "ExceptionType":null, "IsUnique":true, "PrimaryAction":1, "RelatedProspectId":"489c644c-931e-4ed0-bf72-926a2945e72f", "RequestId":"c369ca5a-4474-445e-83fe-0d13a07142ec", "SecondaryAction":2, "Status":0 }
HTTP Response Codes
Code | Description |
---|---|
200 OK | This is the status code for successful API call. |
401 Unauthorized | The API call was made with invalid access credentials. Check your AccessKey and SecretKey. |
400 Bad Request | The message body on the request is not as per API specification. Make sure that content type is set to “application/json” and the JSON body has correct attribute names and structure. |
404 Not Found | The API could not be found. Please check the API signature. |
429 Too Many Requests | API calls exceeded the limit of 25 in 5 second(s) |
500 Internal Server Error | The API called failed. There could be many reasons for it. Check the exception message to get more details. |