ContactService


Click here for a complete list of operations.

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.02 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

Test

The test form is only available for requests from the local machine.

SOAP 1.1

The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values.

POST /api/soap/v1/contact.asmx HTTP/1.1
Host: www.host-tracker.com
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://www.host-tracker.com/Services/CreateContact"

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <AuthHeader xmlns="http://www.host-tracker.com/Services">
      <login>string</login>
      <password>string</password>
      <ticket>string</ticket>
    </AuthHeader>
  </soap:Header>
  <soap:Body>
    <CreateContact xmlns="http://www.host-tracker.com/Services">
      <contactData>
        <id>guid</id>
        <name>string</name>
        <address>string</address>
        <alertDelay>int</alertDelay>
        <activePeriodStart>string</activePeriodStart>
        <activePeriodEnd>string</activePeriodEnd>
        <activeDays>
          <string>string</string>
          <string>string</string>
        </activeDays>
        <subscriptions>
          <Subscription>
            <alertTypes xsi:nil="true" />
            <reportTypes xsi:nil="true" />
            <taskIds xsi:nil="true" />
            <contactIds xsi:nil="true" />
          </Subscription>
          <Subscription>
            <alertTypes xsi:nil="true" />
            <reportTypes xsi:nil="true" />
            <taskIds xsi:nil="true" />
            <contactIds xsi:nil="true" />
          </Subscription>
        </subscriptions>
      </contactData>
    </CreateContact>
  </soap:Body>
</soap:Envelope>
HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <CreateContactResponse xmlns="http://www.host-tracker.com/Services">
      <CreateContactResult>
        <contact>
          <id>guid</id>
          <confirmed>boolean</confirmed>
          <contactType>string</contactType>
          <name>string</name>
          <address>string</address>
          <sendCost>decimal</sendCost>
          <sendCostDirty>boolean</sendCostDirty>
          <alertDelay>int</alertDelay>
          <activePeriodStart>string</activePeriodStart>
          <activePeriodEnd>string</activePeriodEnd>
          <activeDays>
            <string>string</string>
            <string>string</string>
          </activeDays>
          <billingOverlimit>
            <string>string</string>
            <string>string</string>
          </billingOverlimit>
          <subscriptions>
            <Subscription xsi:nil="true" />
            <Subscription xsi:nil="true" />
          </subscriptions>
        </contact>
        <status>string</status>
      </CreateContactResult>
    </CreateContactResponse>
  </soap:Body>
</soap:Envelope>