Documentation

add

Creates virtual business cards.

Restrictions

Maximum of 1000 vCards per method call.

A vCard can't be added if the campaign is archived.

If the vCards have identical information, only one vCard is created.

Request

Request structure in JSON format:

{
  "method": "add",
  "params": { 
    "VCards
[no-highlight[

The vCards to add.

Required

Yes

]no-highlight]
": [{ /* VCardAddItem */ "CampaignId
[no-highlight[

The campaign ID.

Required

Yes

]no-highlight]
": (long), /* required */ "Country
[no-highlight[

Country. A maximum of 50 characters.

Required

Yes

]no-highlight]
": (string), /* required */ "City
[no-highlight[

The city. A maximum of 55 characters.

Required

Yes

]no-highlight]
": (string), /* required */ "CompanyName
[no-highlight[

Name of the organization. Maximum of 255 characters.

Required

Yes

]no-highlight]
": (string), /* required */ "WorkTime
[no-highlight[

The operating hours or client service hours of the business. Set as a string that specifies the range of days of the week, work hours, and minutes.

Days of the week are defined by the numbers from 0 to 6, where 0 is Monday and 6 is Sunday.

Minutes are set as a multiple of 15: 0, 15, 30 or 45.

String format: “day_from;day_to;hour_from;minute_from;hour_to;minute_to“.

For example, the string “0;4;10;0;18;0“ sets the following schedule:

0;4 — Monday to Friday

10;0 — from 10:00 am

18;0 — to 6:00 pm

The schedule may consist of several strings in this format, for example: “0;4;10;0;18;0;5;6;11;0;16;0“. Here, in addition to the previous example, the schedule also includes:

5;6 — Saturday and Sunday

11;0 — from 11:00 am

16;0 — to 4:00 pm

A 24-hour schedule is set using the string “0;6;00;00;00;00“.

Maximum of 255 characters.

Required

Yes

]no-highlight]
": (string), /* required */ "Phone
[no-highlight[

Structure that sets the phone number.

Required

Yes

]no-highlight]
": { /* Phone */ "CountryCode
[no-highlight[

The country code for the phone number. Must contain from 1 to 5 characters. Acceptable values:

  • Beginning with the “+“ symbol and consisting of digits.
  • The value “8” combined with the city code “800”.

For example, “+7“ for Russia.

Required

Yes

]no-highlight]
": (string), /* required */ "CityCode
[no-highlight[

The area code or city code for the phone number. From 1 to 5 digits. Must not be 0.

Required

Yes

]no-highlight]
": (string), /* required */ "PhoneNumber
[no-highlight[

The contact phone number. From 5 to 9 digits. When combined with the country code and city code, it is from 8 to 17 digits.

Required

Yes

]no-highlight]
": (string), /* required */ "Extension
[no-highlight[

The phone extension, if an office PBX system is used. From 1 to 6 digits.

Required

No

]no-highlight]
": (string) }, /* required */ "Street
[no-highlight[

Street. A maximum of 55 characters.

Required

No

]no-highlight]
": (string), "House
[no-highlight[

House number. A maximum of 30 characters.

Required

No

]no-highlight]
": (string), "Building
[no-highlight[

The building or unit number. A maximum of 10 characters.

Required

No

]no-highlight]
": (string), "Apartment
[no-highlight[

The apartment or office number. Maximum of 100 characters.

Required

No

]no-highlight]
": (string), "InstantMessenger
[no-highlight[

A structure that sets the contact for instant messaging.

Required

No

]no-highlight]
": { /* InstantMessenger */ "MessengerClient
[no-highlight[

The type of instant messaging system — icq, jabber, skype or mail_agent.

Required

Yes

]no-highlight]
": (string), /* required */ "MessengerLogin
[no-highlight[

The username (ID) in the instant messaging system. Maximum of 255 characters.

Required

Yes

]no-highlight]
": (string) /* required */ }, "ExtraMessage
[no-highlight[

Additional information on the advertised product or service. Maximum of 200 characters.

Required

No

]no-highlight]
": (string), "ContactEmail
[no-highlight[

Email address. Maximum of 255 characters.

Required

No

]no-highlight]
": (string), "Ogrn
[no-highlight[

The OGRN code for a business registered in Russia. Maximum of 255 characters.

Required

No

]no-highlight]
": (string), "MetroStationId
[no-highlight[

ID of the metro station.

To get the list of metro stations, use the Dictionaries.get method.

Required

No

]no-highlight]
": (long), "PointOnMap
[no-highlight[

Structure that describes the location of the placemark on the map. If not set, the map is marked at the address that was specified for the client.

Required

No

]no-highlight]
": { /* MapPoint */ "X
[no-highlight[

Longitude of the point. From -180 to 180.

Required

Yes

]no-highlight]
": (decimal), /* required */ "Y
[no-highlight[

Latitude of the point. From -90 to 90.

Required

Yes

]no-highlight]
": (decimal), /* required */ "X1
[no-highlight[

Longitude of the lower-left corner of the region on the map. From -180 to 180.

Required

Yes

]no-highlight]
": (decimal), /* required */ "Y1
[no-highlight[

Latitude of the lower-left corner of the region on the map. From -90 to 90.

Required

Yes

]no-highlight]
": (decimal), /* required */ "X2
[no-highlight[

Longitude of the upper-right corner of the region on the map. From -180 to 180.

Required

Yes

]no-highlight]
": (decimal), /* required */ "Y2
[no-highlight[

Latitude of the upper-right corner of the region on the map. From -90 to 90.

Required

Yes

]no-highlight]
": (decimal) /* required */ }, "ContactPerson
[no-highlight[

Contact person. A maximum of 155 characters.

Required

No

]no-highlight]
": (string) }, ... ] /* required */ } }
Parameter Type Description Required
params structure (for JSON) / AddRequest structure (for SOAP)
VCards array of VCardAddItemThe vCards to add.Yes
VCardAddItem structure
CampaignId long

The campaign ID.

Yes
Country string

Country. A maximum of 50 characters.

Yes
City string

The city. A maximum of 55 characters.

Yes
CompanyName string

Name of the organization. Maximum of 255 characters.

Yes
WorkTime string

The operating hours or client service hours of the business. Set as a string that specifies the range of days of the week, work hours, and minutes.

Days of the week are defined by the numbers from 0 to 6, where 0 is Monday and 6 is Sunday.

Minutes are set as a multiple of 15: 0, 15, 30 or 45.

String format: "day_from;day_to;hour_from;minute_from;hour_to;minute_to".

For example, the string "0;4;10;0;18;0" sets the following schedule:

0;4 — Monday to Friday

10;0 — from 10:00 am

18;0 — to 6:00 pm

The schedule may consist of several strings in this format, for example: "0;4;10;0;18;0;5;6;11;0;16;0". Here, in addition to the previous example, the schedule also includes:

5;6 — Saturday and Sunday

11;0 — from 11:00 am

16;0 — to 4:00 pm

A 24-hour schedule is set using the string "0;6;00;00;00;00".

Maximum of 255 characters.

Yes
Phone Phone

Structure that sets the phone number.

Yes
Street string

Street. A maximum of 55 characters.

No
House string

House number. A maximum of 30 characters.

No
Building string

The building or unit number. A maximum of 10 characters.

No
Apartment string

The apartment or office number. Maximum of 100 characters.

No
InstantMessenger InstantMessenger

A structure that sets the contact for instant messaging.

No
ExtraMessage string

Additional information on the advertised product or service. Maximum of 200 characters.

No
ContactEmail string

Email address. Maximum of 255 characters.

No
Ogrn string

The OGRN code for a business registered in Russia. Maximum of 255 characters.

No
MetroStationId long

ID of the metro station.

To get the list of metro stations, use the Dictionaries.get method.

No
PointOnMap MapPoint

Structure that describes the location of the placemark on the map. If not set, the map is marked at the address that was specified for the client.

No
ContactPerson string

Contact person. A maximum of 155 characters.

No
Phone structure
CountryCode string

The country code for the phone number. Must contain from 1 to 5 characters. Acceptable values:

  • Beginning with the "+" symbol and consisting of digits.
  • The value “8” combined with the city code “800”.

For example, "+7" for Russia.

Yes
CityCode string

The area code or city code for the phone number. From 1 to 5 digits. Must not be 0.

Yes
PhoneNumber string

The contact phone number. From 5 to 9 digits. When combined with the country code and city code, it is from 8 to 17 digits.

Yes
Extension string

The phone extension, if an office PBX system is used. From 1 to 6 digits.

No
InstantMessenger structure
MessengerClient string

The type of instant messaging system — icq, jabber, skype or mail_agent.

Yes
MessengerLogin string

The username (ID) in the instant messaging system. Maximum of 255 characters.

Yes
MapPoint structure
X decimal

Longitude of the point. From -180 to 180.

Yes
Y decimal

Latitude of the point. From -90 to 90.

Yes
X1 decimal

Longitude of the lower-left corner of the region on the map. From -180 to 180.

Yes
Y1 decimal

Latitude of the lower-left corner of the region on the map. From -90 to 90.

Yes
X2 decimal

Longitude of the upper-right corner of the region on the map. From -180 to 180.

Yes
Y2 decimal

Latitude of the upper-right corner of the region on the map. From -90 to 90.

Yes

Response

Response structure in JSON format:

{
  "result": { 
    "AddResults
[no-highlight[

Results of adding vCards.

]no-highlight]
": [{ /* ActionResult */ "Id
[no-highlight[

ID of the created vCard. Returned if there are no errors; see the section Operations on object arrays.

]no-highlight]
": (long), "Warnings
[no-highlight[

Warnings that occurred during the operation.

]no-highlight]
": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ], "Errors
[no-highlight[

Errors that occurred during the operation.

]no-highlight]
": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ] }, ... ] } }
Parameter Type Description
result structure (for JSON) / AddResponse structure (for SOAP)
AddResults array of ActionResultResults of adding vCards.
ActionResult structure
Id long

ID of the created vCard. Returned if there are no errors; see the section Operations on object arrays.

Warnings array of ExceptionNotification

Warnings that occurred during the operation.

Errors array of ExceptionNotification

Errors that occurred during the operation.

Examples

Request example
{
  "method" : "add",
  "params" : {
    "VCards" : [
      {
        "Phone" : {
          "CityCode" : "812",
          "Extension" : "89",
          "PhoneNumber" : "123-45-67",
          "CountryCode" : "+7"
        },
        "WorkTime" : "0;3;10;0;18;0;4;6;10;0;11;0",
        "Country" : "Russia",
        "CompanyName" : "Some Company DvKqXuiphd",
        "CampaignId" : 4193065,
        "PointOnMap" : {
          "X" : 39.724068,
          "Y" : 47.222555,
          "X1" : 39.722020,
          "Y1" : 47.221160,
          "X2" : 39.726116,
          "Y2" : 47.223951,

        },
        "City" : "Moscow"
      }
    ]
  }
}
Response example
{
  "result" : {
    "AddResults" : [
      {
        "Id" : 13070322
      }
    ]
  }
}
Sample response with warning

If the vCard being added is a duplicate of a previously created one, the new vCard is not created and a warning is issued.

{
  "result" : {
    "AddResults" : [
      {
        "Id" : 13070292,
        "Warnings" : [
          {
            "Code" : 10100,
            "Message" : "The card indicated duplicates a card created earlier"
          }
        ]
      }
    ]
  }
}