Welcome

CallMeNow - REST API reference
The Call Me Now API allows you to implement a feature on your website which gives insurance prospects a way to be instantly contacted by an agent without calling in and navigating an IVR phone routing system. Call Me Now provides an extra level of customer attention.

Initial Setup

Contact your Answer account manager to setup and configure the following detail:

  1. Affinity Group(s)
  2. Development URL
  3. Username and password
  4. Example Auth Header Info
  5. Base URL
  6. Endpoints and Resources

Base URL

EnvironmentBase URLs
DevelopmentContact your Answer account manager
ProductionContact your Answer account manager

Endpoints and Resources

ResourcesEndpointDescription
IsCallMeNowAvailableContact your Answer account managerCheck if an agent is available for a CallMeNow Request
CallMeNowContact your Answer account managerCreate a CallMeNow lead.

Method

All Methods are POST methods.

ResourceMethod
IsCallMeNowAvailablePOST
CallMeNowPOST
HeadersRequiredNotes
IsCallMeNowAvailableAuthorization: Basic
Content-Type: application/json
Accept: application/json
Basic authentication requires base64 username:password
CallMeNowAuthorization: Basic
Content-Type: text/plain
Accept: application/json
AffinityGroup: VALID_AFFINITY_GROUP_NAME
Basic Authentication requires base64 username:password.

AffinityGroup filtering is applied on Answer's side.

Authentication

Basic Authentication is required to confirm that you are available to make any CallMeNow requests.

Server Side Authentication
When our server wants the user agent to authenticate itself towards the server, it must respond appropriately to unauthenticated requests. Unauthenticated requests return a response header containing a HTTP 401 Unauthorized status

Client Side Authentication
When the user agent wants to send the server authentication credentials it may use the Authorization field.

The Authorization field is constructed as follows:

  1. The username and password are combined with a single colon.
  2. The resulting string is encoded into an octet sequence.
  3. The resulting string is encoded using a variant of Base64.
  4. The authorization method and a space (i.e. "Basic " is then put before the encoded string)

Example: view hide

How to format your basic authentication

For example, if the browser uses Aladdin as the username and OpenSesame as the password, then the field's value is the base64-encoding of Aladdin:OpenSesame, or QWxhZGRpbjpPcGVuU2VzYW1l. Then the Authorization header will appear as:

Authorization: Basic QWxhZGRpbjpPcGVuU2VzYW1l

Request Objects

IsCallMeNowAvailable
Is in JSON format and requires a POST method to request availability.

An IsCallMeNowAvailable Object contains the following fields:

AttributeTypeDescription
StatestringValid two character state abbreviation (i.e. CA, TX, CO)
LobstringValid Line Of Business (i.e. AUTO)
ZipstringValid zipcode that matches with supplied state abbreviation.

Example: view hide

IsCallMeNowAvailable Minimum requirements example:
{
    "State": "CA",
    "Lob": "AUTO",
    "Zip": "91770"
}

CallMeNow
Is in XML format and requires a POST method to perform a CallMeNow request.

A CallMeNow Object is in XML format and contains the following required string fields:

AttributexpathDescription
Surname/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/InsuredOrPrincipal/GeneralPartyInfo/NameInfo/PersonName/SurnamePolicy Holders Last Name
GivenName/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/InsuredOrPrincipal/GeneralPartyInfo/NameInfo/PersonName/GivenNamePolicy Holders First Name
PhoneNumber/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/InsuredOrPrincipal/GeneralPartyInfo/Communications/PhoneInfo[./CommunicationUseCd='Home']/PhoneNumberPolicy Holders Home Phone Number
EmailAddr/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/InsuredOrPrincipal/GeneralPartyInfo/Communications/EmailInfo/EmailAddrPolicy Holders contact Email Address
Addr1/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/PersPolicy/PersApplicationInfo/InsuredOrPrincipal/GeneralPartyInfo/Addr/Addr1[1]Policy Holders Mailing Address's Address Line1
City/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/PersPolicy/PersApplicationInfo/InsuredOrPrincipal/GeneralPartyInfo/Addr/City[1]Policy Holders Mailing Address's City
StateProvCd/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/PersPolicy/PersApplicationInfo/InsuredOrPrincipal/GeneralPartyInfo/Addr/StateProvCd[1]Policy Holders Mailing Address'sState
PostalCode/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/PersPolicy/PersApplicationInfo/InsuredOrPrincipal/GeneralPartyInfo/Addr/PostalCode[1]Policy Holders Mailing Address'sZipCode
LOBCd/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/ PersAutoLineBusiness/LOBCdLine Of Business: AUTO

Example: view hide

CallMeNow Minimum requirements example:
<ACORD>
 <InsuranceSvcRq>
  <PersAutoPolicyQuoteInqRq>
   <InsuredOrPrincipal>
    <GeneralPartyInfo>
     <NameInfo>
      <PersonName>
       <Surname>Lastname</Surname>
       <GivenName>Firstname</GivenName>
      </PersonName>
     </NameInfo>
     <Communications>
      <PhoneInfo>
       <CommunicationUseCd>Home</CommunicationUseCd>
       <PhoneNumber>6265551212</PhoneNumber>
      </PhoneInfo>
      <EmailInfo>
       <EmailAddr>emailaddress@abc.com</EmailAddr>
      </EmailInfo>
     </Communications>
    </GeneralPartyInfo>
    <InsuredOrPrincipalInfo>
     <PersonInfo/>
    </InsuredOrPrincipalInfo>
   </InsuredOrPrincipal>
   <PersPolicy>
    <PersApplicationInfo>
     <InsuredOrPrincipal>
      <GeneralPartyInfo>
       <Addr>
        <AddrTypeCd>MailingAddress</AddrTypeCd>
        <Addr1>999 Murdock Rd</Addr1>
        <City>Marietta</City>
        <StateProvCd>GA</StateProvCd>
        <PostalCode>30062</PostalCode>
       </Addr>
      </GeneralPartyInfo>
     </InsuredOrPrincipal>
    </PersApplicationInfo>
    <QuoteInfo>
     <CompanysQuoteNumber/>
    </QuoteInfo>
   </PersPolicy>
   <PersAutoLineBusiness>
    <LOBCd>AUTO</LOBCd>
    <PersDriver>
     <DriverInfo>
      <PersonInfo/>
     </DriverInfo>
     <GeneralPartyInfo>
      <NameInfo>
       <PersonName>
        <Surname>Lastname</Surname>
        <GivenName>Firstname</GivenName>
       </PersonName>
      </NameInfo>
     </GeneralPartyInfo>
    </PersDriver>
   </PersAutoLineBusiness>
  </PersAutoPolicyQuoteInqRq>
 </InsuranceSvcRq>
</ACORD>

Response Object

Our response object contains everything you need to understand the status of your request.

Response Attributes are as follows:

FieldDescriptionNotes
SessionKeyThe GUID generated for your request call.
IndividualIDCreated or existing users unique IDConditional Response value
TAMID7 character unique identifier for the user.Conditional Response value
InformationResponse informationConditional Response value
ValidationError ObjectAn array of zero or more ValidationError objectsThere can be zero or more validation errors
StatusSuccess or Error Status
ErrorDescription
ErrorCodeA string indicating the kind of error, used to further qualify the HTTP response code

Example: view hide

Standard response object layout example:
{ 
  "SessionKey": "", 
  "IndividualId": "", 
  "TAMID": "", 
  "Information": "", 
  "ValidationError": [ 
    { 
      "FieldName": "", 
      "Message": "" 
    }, 
  ], 
  "Status": "", 
  "ErrorDescription": "", 
  "ErrorCode": 
}

ValidationError Object
The ValidationError object is used to identiy fields with issue and explain the problem.

ValidationError Attributes are as follows:

FieldDescriptionNotes
FieldNameIdentifies the field with the validation error
MessageDescribes the actual Error/validation identifed.

Example: view hide

Standard ValidationError object layout example:
{ 
  "FieldName": "State", 
  "Message": "State does not match with postal code." 
} 

Response Object
A successful response objects will contain:

ResourceResponse FieldsNotes
IsCallMeNowAvailableSessionKey
Information
ValidationError
Status
ErrorDescription
ErrorCode
ValidationError will be blank on a successful response. We should never expect the individualId or TAMID fields to be returned with an IsCallMeNowAvailable response.
CallMeNowSessionKey
IndividualId
TAMID
ValidationError
Status
ErrorDescription
ErrorCode
ValidationError will be blank on a successful response. We sholuld never expect the information or TAMID fields to be returned with an CallMeNow response

Example: view hide

Successful Response examples:

IsCallMeNowAvailable Successful Response

{ 
  "SessionKey":"d39ec42d-57c6-4393-aac0-a34cfafd663f", 
  "Information": "AGENT AVAILABLE", 
  "ValidationError": [ ], 
  "Status": "SUCCESS", 
  "ErrorDescription": "", 
  "ErrorCode": 0 
} 

CallMeNow Successful Response

{ 
  "SessionKey":"8ce0692c-44db-418b-9b1d-e657dbef5e1d", 
  "IndividualId": 99999999, 
  "TAMID": "XYZXYZX", 
  "ValidationError": [ ], 
  "Status": "SUCCESS", 
  "ErrorDescription": , 
  "ErrorCode": 0 
} 

Errors

CallMeNow uses HTTP responses to return "error" status back to the requestor. An ErrorCode as well as an ErrorDescription will be returned if not successful.

ErrorCodeError Description
100Not a valid XML input
101Auto - Validation Error
102Auto - AffinityGroup must be provided in header request
103Auto - Not a valid AffinityGroup
104Auto - Not an allowable AffinityGroup
105Auto - Available Agent Validation Error on Lob/State/Zip
106Auto - Agent Availablity Error
107Auto - Unable to Tranform ACORD Format
108Auto - Lead Creation Response Error
200Auto - Agent Not Available
401Authentication Error

Example: view hide

Error Response examples:

IsCallMeNowAvailable Error Response

{ 
  "SessionKey": "fa61b04d-a111-4163-9ce1-86ae07a6c64d", 
  "Information": "", 
  "ValidationError": [ 
  	{ 
  	  "FieldName": "Lob", 
  	  "Message": "CallMeNowAvailableReq.Lob - Invalid Lob" 
  	}, 
  	{ 
  	  "FieldName": "State", 
  	  "Message": "CallMeNowAvailableReq.State Invalid State" 
  	}, 
  	{ 
  	  "FieldName": "Zip", 
  	  "Message": "CallMeNowAvailableReq.Zip - Invalid Zip" 
  	}, 
  	{ 
  	  "FieldName": "State", 
  	  "Message": "State does not match with PostalCode" 
  	} 
  ], 
  "Status": "ERROR", 
  "ErrorDescription": "ValidationError", 
  "ErrorCode": 105
}

CallMeNow Error Response

{ 
  "SessionKey": "febe0707-9d77-4286-b4c5-8ef645c3e075", 
  "IndividualId": 0, 
  "TAMID": "", 
  "ValidationError": [ ], 
  "Status": "ERROR", 
  "ErrorDescription": "Not a valid xml input", 
  "ErrorCode": 100
}

Validation

ResourceNot Null or White SpacesSpecial Logic
IsCallMeNowAvailable State,
Zip,
LOB
State: Validate US State abbreviation.

Zip: Validate Postal Code is Numeric, is 5 chars, Does not equal 99999.

Lob: Validate Line Of Business: LOB must equal “AUTO”

State & Zip: state and zipcode must be a matching combination.
CallMeNow/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/InsuredOrPrincipal/GeneralPartyInfo/NameInfo/PersonName/Surname

/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/PersPolicy/PersApplicationInfo/InsuredOrPrincipal/GeneralPartyInfo/Addr[1]/Addr1

/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/PersPolicy/PersApplicationInfo/InsuredOrPrincipal/GeneralPartyInfo/Addr[1]/City

/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/PersPolicy/PersApplicationInfo/InsuredOrPrincipal/GeneralPartyInfo/Addr[1]/StateProvCd

/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/PersPolicy/PersApplicationInfo/InsuredOrPrincipal/GeneralPartyInfo/Addr[1]/PostalCode

/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/InsuredOrPrincipal/GeneralPartyInfo/Communications/PhoneInfo[CommunicationUseCd='Home']/PhoneNumber
/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/PersPolicy/PersApplicationInfo/InsuredOrPrincipal/GeneralPartyInfo/Addr[1]/StateProvCd : Validates against the two character US State abbreviation

/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/PersPolicy/PersApplicationInfo/InsuredOrPrincipal/GeneralPartyInfo/Addr[1]/PostalCode : Valid Postal Code is Numeric, is 5 chars, Does not equal 99999

/ACORD/InsuranceSvcRq/PersAutoPolicyQuoteInqRq/InsuredOrPrincipal/GeneralPartyInfo/Communications/PhoneInfo[CommunicationUseCd='Home']/PhoneNumber : Valid Phone Number: Must have a “CommunicationUseCd” of “Home” or “Business”, Must be numeric, Can me 10 or 11 chars.
If 10 chars, should not start with 0 or 1
If 11 chars, 2nd must not start with 0 or 1