Available api SOAP operations with contacts

Operations with user contacts

Authentication for every method performed through AuthHeader Soap header with fields:

login - user login, must be specified with password, incompatible with ticket
password - user password, must be specified with login, incompatible with ticket
ticket - ticket from SignIn API call of user service, incompatible with login, password pair

You should specify only ticket or only (login, password) pair in auth header.
Soap client fault messages on auth. fail:

AccessDenied - access to api is denied. Also coused by wrong user billing package
IncorrectLoginOrPassword - raised when login and/or password is incorrect in auth. header
TicketExpired - provided ticked is expired
WrongTicket - ticket could not be decrypted

The following operations are supported. For a formal definition, please review the Service Description.

ConfirmContact
Confirm contact via specified code.
Params:
- contactId - id (GUID) of contact to confirm
- code - code (was sent to address during creation or code resend)
Result is ContactOperationResult. For details about ContactOperationResult see CreateContact, UpdateContact methods.
Result contains new status of contact. If confirmation succeeded then status will be Confirmed. If confirmation failed status well be CodeFail.

ConfirmContacts
Confirm contacts via array of ContactConfirmation record.
Params:
- codes - array of ContactConfirmation.
  ContactConfirmation:
  - id - id of contact to confirm
  - code - code for confirmation
Result is array of ContactOperationResult. For details about ContactOperationResult see CreateContact, UpdateContact methods.
Result contains new statuses for contacts. If confirmation succeeded then status will be Confirmed. If confirmation failed status well be CodeFail.

CreateContact
Create contact from ContactEditableData derived classes: EmailContactEditableData, SmsContactEditableData, IMContactEditableData, VoiceCallEditableData.
Params:
- ContactEditableData - could not be used for Create method but for Update methods:
  - id - contact id (GUID) should be specified only in UpdateContacts operation. For other method should be null (not set).
  - name - user provided contact name
  - address - contact address
  - alertDelay - alert sending delay in minutes. See GetAlertDelays method for available values
  - activePeriodStart - string in format hh:mm (or null if contact is active for all time), specify start of contact daily activity period.
    Should be specified with activePeriodEnd. If activePeriodStart > activePeriodEnd then activity period calculated as
    period from activePeriodStart day time to the end of the day plus period from next day start to next day activePeriodEnd time.
    If alert created when contact is outside activity period then it will not be sent to this contact.
  - activePeriodEnd - string in format hh:mm (or null if contact is active for all time), specify period of contact activity.
    Should be specified with activePeriodStart. If activePeriodStart > activePeriodEnd then activity period calculated as
    period from activePeriodStart day time to the end of the day plus period from next day start to next day activePeriodEnd time.
    If alert created when contact is outside activity period then it will not be sent to this contact.
  - activeDays - array of week days when contact is active or null if contact is active for all days. Available values: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
  - subscriptions - subscriptions for this contact (see subscription service AddSubscriptions for details).
- EmailContactEditableData:
  - reportFormat - format of emails. Currently supported: Text, ShortText. Planned: HTML, Pdf(for reports)
  - sendNews - could contact be used for news delivery
  - sendPressRelease - could contact be used for press release delivery
  - sendBillingNotifications - send billing notifications (about low balance, overlimits and others)
- SmsContactEditableData:
  - gateway - sms gateway of contact. See GetSmsGateways for details
- IMContactEditableData:
  - gateway - instant messaging gateway of contact. See GetIMGateways for details
- VoiceCallEditableData:
  - Currently has no additional field. VoiceCall gateway is twiliovoice. Send cost: $0.04 for US carriers, $0.222 for other.
Result is ContactOperationResult with fields:
- contact - created Contact (derived types)
- status - status of contact creation:
  - Confirmed - contact created in confirmed state
  - ConfirmedOverlimited - contact is confirmed but overlimited by contact count
  - LowSmsBalance - could not send contact confirmation code due to low balance
  - CodeSent - contact created and confirmation code was sent. Contact become active after confirmation
  - CodeFail - contact create but code sending failed. Try to resend code after some time.
Soap client faults:
- UncomplitedData - ContactEditableData (but not derived type) specified for task creation
- SimilarExists - similar contact is allready exists. Contact similarity is detected by contact type, contact address, contact gateway and contact alert sending delay
- EmptyAddress - address was not specified
- WrongAlertDelay - wrong alert delay
- WrongActivePeriodInterval - wrong contact activity period
- WrongActiveDay - wrong contact activity days
- WrongEmailFormat - specified report format is incorrect. See reportFormat field available values in EmailContact or EmailContactEditableData
- WrongSmsGateway - wrong sms gateway specified. See GetSmsGateways for available gateways.
- WrongIMGateway - wrong instant messaging gateway specified. See GetIMGateways for available gateways.
- WrongContactType - wrong contact type specified. See GetContactTypes for available gateways.
- Subscription error codes - see subscription service AddSubscriptions

CreateContacts
Create contacts from array of ContactEditableData (array of derived classes: EmailContactEditableData, SmsContactEditableData, IMContactEditableData, VoiceCallEditableData).
Params:
- array of ContactEditableData - see CreateContact for details.
- returnBadFormatedData - if false then wrong data in one contact will result in fail of whole batch.
  If true then contacts with correct data will be created; wrong data and created contacts will be returned as result of method.
Result is BatchContactOperationResult with fields:
- contacts - created contacts - array of Contact (derived types)
- badContactEditableData - status of contact creation - array of BadContactEditableData:
  - index - index of contact data in input array
  - data - wrong contact data
  - code - error code, same as in Soap client faults messages (see CreateContact method)
  - message - fault code description
Soap client faults:
- EmptyContactData - contact data array is empty or was not specified
- Other Soap faults same to faults in CreateContact method

DeleteContact
Delete contact with specified contactId (GUID). If contact does not exists method will silently end without error.
Params:
- contactId - id (GUID) of contact to delete.
Result is void (unit, none).

DeleteContacts
Delete contact with specified array of id. If some contact does not exists method will silently continue without error.
Params:
- contactIds - array of contact ids (GUIDs) to delete.
Result is void (unit, none).

DeleteContactsByFilter
Delete contact by specified ContactFilter.
Params:
- filter - ContactFilter. For details about filter see GetContactsByFilter method.
Result is void (unit, none).
Soap client faults:
- WrongContactType - specified wrong contact type in filter

GetAlertDelays
Return available alert sending delays in minutes. Currently: 0 (default - instant alert), 5, 15, 30, 60, 180 (3 hours), 720 (12 hours)

GetContact
Get contact by id (GUID).
Params:
- id - contact id to search for.
- additionalInfo - ContactInformation flags. See GetContacts for details
Result: Contact derived type - EmailContact, SmsContact, IMContact, VoiceCallContact. See GetContacts for details. null if contact was not found.

GetContactTypes
Return available contact types. Currently: Email, SMS, IM, VoiceCall

GetContacts
Get all user contacts.
Params:
- additionalInfo - combinartion of simple ContactInformation flags:
  - 0x00 (None) - no additional info
  - 0x01 (Subscriptions) - return array of Subscription for every contact (see subscription service for details)
Result: array of Contact derived types - EmailContact, SmsContact, IMContact, VoiceCallContact
- Contact:
  - id - contact id (GUID). Could be used in subscription API calls
  - confirmed - contact is confirmed (sended confirmation code was provided for contact)
  - contactType - one of available contact types. See GetContactTypes method
  - name - user provided contact name
  - address - contact address
  - sendCost - cost of one notification
  - alertDelay - alert sending delay in minutes. See GetAlertDelays method
  - activePeriodStart - string in format hh:mm, specify start of contact daily activity period.
    Should be specified with activePeriodEnd. If activePeriodStart > activePeriodEnd then activity period calculated as
    period from activePeriodStart day time to the end of the day plus period from next day start to next day activePeriodEnd time.
    If alert created when contact is outside activity period then it will not be sent to this contact.
  - activePeriodEnd - string in format hh:mm, specify period of contact activity.
    Should be specified with activePeriodStart. If activePeriodStart > activePeriodEnd then activity period calculated as
    period from activePeriodStart day time to the end of the day plus period from next day start to next day activePeriodEnd time.
    If alert created when contact is outside activity period then it will not be sent to this contact.
  - activeDays - array of week days when contact is active. Available values: Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday
  - billingOverlimit - array of overlimit reasons. When no overlimit array is empty. Currently only one reason supported - Contact - indicate overlimit by contact count in current package.

GetContactsByFilter
Get contacts by filter.
Params:

ContactFilter:

Hint 1. All filter fields are optional and could be combined together.

Hint 2. Specifying single filtered value (for ex. address) and filtered value collection (for ex. addresses) results in filtered value collection with all specified values (in ex. specified address and specified addresses).

Hint 3. If several fields are specified then they are combined via AND condition.

ids - contact ids for search for

excludeIds - if true then exclude specified ids

contactType - search for specified contact type

contactTypes - search for specified contact types

excludeContactTypes - if true - exclude specified contact types

confirmed - true - search for confirmed only, false - search only for not confirmed, null - search both

overlimited - true - search for overlimited only, false - search only for not overlimited, null - search both

acceptBillingNotifications - true - search for contacts which accepts billing notifications,
false - search only for contacts which does not accept billing notifications, null - search both

address - search for contacts with specified address

addresses - search for contacts with specified addresses

excludeAddresses - search for contacts with not specified addresses

additionalInfo - ContactInformation flags. See GetContacts for details

Result is array of Contact derived types - EmailContact, SmsContact, IMContact, VoiceCallContact. See GetContacts for details.

Soap client faults:

WrongContactType - specified wrong contact type

GetIMGateways
Return available Instant Messaging gateways. Currently: SkypeChat, GTalk

GetSmsGateways
Return available SMS gateways. Currently: infobip($0.033), twiliosms($0.04), clickatell($0.0468), clickatella($0.117), skype($0.066)

ResendCode
Resend confirmation code for contact, specified by id.
Params:

contactId - id (GUID) of contact.

Result is ContactOperationResult. For details about ContactOperationResult see CreateContact, UpdateContact methods.
Result contains status of code sending.

UpdateContact
Update existing contact. NotFound Soap client fault will be rised if contact will not be found.
Params:

contactId - id of contact (GUID), required.

contactData - ContactEditableData or it's derived type (see CreateContact method), required.

Result is ContactOperationResult with fields:

contact - updated contact information in form of Contact derived type

status - new contact status. Contact will need to be confirmed if you change address and/or gateway of it.

Confirmed - changed contact remains confirmed
Updated contact could become confirmed if there are allready exists confirmed contact with same pair (address, gateway).

ConfirmedOverlimited - changed contact remains confirmed and overlimited

LowSmsBalance - updated contact became unconfirmed but code was not send due to low sms balance

CodeSent - updated contact became unconfirmed and new code was sent to specified address

CodeFail - updated contact became unconfirmed but code was not send due to server error. Try resend code after some time.

CodeSentEarlier - address and gateway of contact was not changed but contact was unconfirmed. Code for it was sent earlier and will not be resend by this method.

Soap client faults:

SimilarExists - similar contact is allready exists. Contact similarity is detected by contact type, contact address, contact gateway and contact alert sending delay

WrongAlertDelay - wrong alert delay

WrongActivePeriodInterval - wrong contact activity period

WrongActiveDay - wrong contact activity days

WrongEmailFormat - specified report format is incorrect. See reportFormat field available values in EmailContact or EmailContactEditableData

WrongSmsGateway - wrong sms gateway specified. See GetSmsGateways for available gateways.

WrongIMGateway - wrong instant messaging gateway specified. See GetIMGateways for available gateways.

WrongContactType - wrong contact type specified. See GetContactTypes for available gateways.

Subscription error codes - see subscription service AddSubscriptions

UpdateContacts
Update contacts using array of ContactEditableData. Contacts for update are detected by id field of ContactEditableData.
If you do not specify this field, update will fail with code NoIdInContactData according to input parameter returnBadFormatedData (see below).
Params:

contactData - array of ContactEditableData. Field id in every record is required.
Array should not be empty or null (this case will result in EmptyContactData fail)

returnBadFormatedData - specify how to process wrong formated user input. if false - one wrong record in input array will result in Soap client fail (no tasks will be updated).
If true - wrong input reports will be collected and returned as result of method call. Correct data will result in task updated. Updated tasks will be also returned (See Result below).

Result is BatchContactOperationResult with fields:

contacts - array of ContactOperationResult with updated contact and new contact status. See UpdatedContact for ContactOperationResult description.

badContactEditableData - array of BadContactEditableData.
BadContactEditableData:

index - index of contact data in input array. If it is null then contactId will specify contact id

contactId - contact id for which modification attempt was made. If it is null then index field will specify the index of wrong data in input array.

data - wrong contact data

code - error code, same as in Soap client faults messages (see CreateContact method)

message - fault code description

Soap client faults:

NoIdInContactData - id was not specified in contact data

EmptyContactData - input array of data is empty

SimilarExists - similar contact is allready exists. Contact similarity is detected by contact type, contact address, contact gateway and contact alert sending delay

WrongAlertDelay - wrong alert delay

WrongActivePeriodInterval - wrong contact activity period

WrongActiveDay - wrong contact activity days

WrongEmailFormat - specified report format is incorrect. See reportFormat field available values in EmailContact or EmailContactEditableData

WrongSmsGateway - wrong sms gateway specified. See GetSmsGateways for available gateways.

WrongIMGateway - wrong instant messaging gateway specified. See GetIMGateways for available gateways.

WrongContactType - wrong contact type specified. See GetContactTypes for available gateways.

Subscription error codes - see subscription service AddSubscriptions

UpdateContactsByFilter
Update contacts by ContactFilter and ContactEditableData.
Params:

filter - ContactFilter. For details about filter see GetContactsByFilter method.

contactData - ContactEditableData. For details about contactData see UpdateContact method.

Result is array of ContactOperationResult. For details about ContactOperationResult see UpdateContact method.

Soap client faults:

SimilarExists - similar contact is allready exists. Contact similarity is detected by contact type, contact address, contact gateway and contact alert sending delay

WrongAlertDelay - wrong alert delay

WrongActivePeriodInterval - wrong contact activity period

WrongActiveDay - wrong contact activity days

WrongEmailFormat - specified report format is incorrect. See reportFormat field available values in EmailContact or EmailContactEditableData

WrongSmsGateway - wrong sms gateway specified. See GetSmsGateways for available gateways.

WrongIMGateway - wrong instant messaging gateway specified. See GetIMGateways for available gateways.

WrongContactType - wrong contact type specified. See GetContactTypes for available gateways.

Subscription error codes - see subscription service AddSubscriptions