Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 7 Next »

Inserts a lead into a designated Campaign/Allocation ready to be dialed.

The timing of when the lead will be dialed depends on the normal lead prioritisation mechanism (priority, callback date, balance mode etc) however the lead won't be considered until the next dialer cache refresh occurs. Cache refreshes occur every two minutes, so on average, injected leads will take at least one minute before they will be considered for dialing.

The endpoint InsertLeadFast replaces the original InsertLead method. The new endpoint takes the same arguments but has enhanced error codes and as the name implies is faster than the original InsertLead endpoint.

Performance considerations

Injection of leads into Noojee Campaigner is a 'heavy weight' process (it can take a long time) as each lead needs to be de-duplicated and activated.

In order to protect the core function of the PBX the end point is rate limited. The api allows multiple concurrent calls limited to (No. of hardware threads / 2) and each call we never complete in less than 100 ms. On larger databases the time required to complete each insert may increase further.

Note: the rate limiting is across both the UpdateLeadFast and InsertLeadFast combined.

If you exceed the above rates the system will queue additional requests. This may result in your call to the endpoint timing out (currently timeout is 1 minute). If your call to the InsertLeadFast endpoint times out then the lead will not be inserted and you will need to retry the insertion.

Queue insertions

As the end point is rate limited we strongly recommend that you queue the inserts within your system and include retry logic if the insert fails. This will deal with the above rate limiting logic as well as provide guaranteed delivery even if the Noojee PBX goes down for maintenance.


Retries

You must expect calls to InsertLeadFast to fail so make certain your code can retry the action. If an insert fails then wait a couple of minutes before retrying.

Entry point:

Lead data must be POSTed and encoded as json.

https://<server host>/servicemanager/rest/CampaignAPI/insertLeadsFast


URL Parameters:

ParameterDescriptionRequired
fTemplateId

Campaign Template id of the Template that the lead will be associated with.

See 16.0 Get Campaign Template List to obtain Template Id's

Yes
fCampaignId

Campaign id of the Campaign that the lead will be associated with.

See 17.0 Get Campaign List to obtain a list of campaign Id's.

Yes
fAllocationId

Allocation id of the Campaign that the lead will be associated with.

See 18.0 Get Allocation List to obtain a list of allocations.

Yes
allowDuplicatesIf true checking for duplicate phone numbers will NOT be performed .No
apiKeyapi key provided by Noojee SupportYes


System fields that can be part of the json data:

ParameterDescriptionRequired
njExternalLeadIdA reference, account number or the like taken from the external data source. Also used to identify lead when updates are made.No
njCallBackDate

The date and time on which the lead is to be called. If not specified the lead is treated as a 'new' lead and will be called on a first come first served basis.

Format is "yyyy/MM/dd HH:mm". Note that when setting a call back date the time is treated as being in the Contact Hours timezone.

If you want to inject a lead to be dialed immediately then you need to convert the current time to the contact hours time. Noojee Contact will normally be configured so the 'system time' is in the timezone where the main team is located.

No
njPriorityA priority between 0 and 100. The lower the number the higher the priority. Higher priority leads will be called before lower priority calls. Default priority is 10.No
njContactHoursSets the Contact Hours for the lead. If not passed the lead will default to the Campaign Templates default Contact Hours.No

Syntax

The format of the data posted is a json containing one or more sets of name value pairs:

{"fieldname1": "lead 1 field 1 value", "fieldname2" , "lead 1field 2 value"}, {"fieldname1": "lead 2 field 1 value", "fieldname2" , "lead 2 field 2 value"}

Curl Sample query:

curl -v -H "Accept: application/json" -H "Content-Type: application/json" -X POST 
-d '{"Name":"Jane Smith","StreetAddress":"Suite 8/10 Hoddle St", "City": "Abbotsford", "State":"Vic", "PostCode":"3064", "FirstPhone":"0383218199"}' 
'https://<server host>/servicemanager/rest/CampaignAPI/insertLeadFast?fTemplateId=41&fCampaignId=41&fAllocationId=38&apiKey=f863246a-973e-11e6-8784-08002718f5b5&allowDuplicates=true'


Sample success response:

{"code":0,"message":"OK"}

Error Codes

The API returns a HTTP status code and an json error code as follows:

HTTP status of 200 is returned when the lead was successfully inserted or updated.

HTTP status of 400 is returned when you passed some invalid data.

HTTP status of 500 is returned if our system throws an exception (our code is broken).

CodeMessageHTTP statusDescription
0OK200The lead was successfully inserted or updated.
101COULDNT_FIND_THE_LEAD400For an update, the njExternalLeadId didn't match a lead
102NO_PHONE_FIELDS400For an import the lead doesn't have and phone numbers.
103EXCEPTION500
104DNC400The lead's phone numbers are on the DNC list
105DUPLICATE400There is already a lead with this phone number
106INVALID_DISPOSTION400When updating, the supplied disposition doesn't exist.
107DISPOSTION_ISNT_SET_AND_NOCHANGE_SPECIFIED400When updating a a lead the disposition can be omitted, and <NO CHANGE> specified. But this is an error condition if the lead doesn't already have a disposition.
108IMPORT_BUT_NOCHANGE_SPECIFIED400Tried to insert a lead but a field contained the value '<NO CHANGE>' which is only valid for updates.
109TIMEOUT_TOO_MANY_CONCURRENT_REQUESTS400

There are too many concurrent insert/update API requests. Wait a bit and then retry the insert/update.

Currently a call will timeout if it is delayed by more than 1 minute.

110LEAD_NOT_UPDATED_DUE_TO_CONFLICT400The lead update caused a conflict with another update and failed. This usually means that a user was editing the lead whilst you were trying to update it via the api. This type of issues should be rare as in most cases the user will see the error not the api. When the user sees the error they will be given the opportunity to merge the two leads via a specialised merge lead screen. If the api recieves this error then you will need to manually intervene to ensure that data isn't over-written which a simply retry is likely to do.
  • No labels