POST 3/contacts?surveyId={surveyId}&logComment={logComment}

Definition

POST - 3/contacts?surveyId={surveyId}&logComment={logComment}

Create a new contact in a survey

Required roles: Contacts (write)

Request information

Uri parameters

Name	Description	Type	Additional information
surveyId The survey identifier. Always add a contact immediately to a survey. Contacts without a survey are no longer available in our tool. Type integer Additional info Required
surveyId	The survey identifier. Always add a contact immediately to a survey. Contacts without a survey are no longer available in our tool.	integer	Required
logComment Type string Additional info Optional
logComment		string	Optional

Request body fields

The new contact.

Name	Description	Type	Additional information
DateToBeMailed Date and time on which the invitation will be sent. If not passed, the invitation will be sent once the survey is live or immediately if the survey is already live. Only applies if the SurveyId is passed in the querystring. Type date Additional info ISO 8601 format
DateToBeMailed	Date and time on which the invitation will be sent. If not passed, the invitation will be sent once the survey is live or immediately if the survey is already live. Only applies if the SurveyId is passed in the querystring.	date	ISO 8601 format
DateToExpire Date and time on which the invitation should expire and the contact can no longer respond to the survey, if not available the invitation will be active until the survey is closed. Only applies if the SurveyId is passed in the querystring. Type date Additional info ISO 8601 format
DateToExpire	Date and time on which the invitation should expire and the contact can no longer respond to the survey, if not available the invitation will be active until the survey is closed. Only applies if the SurveyId is passed in the querystring.	date	ISO 8601 format
FirstName Given name. Type string Additional info Max length: 50
FirstName	Given name.	string	Max length: 50
LastName Family name. Type string Additional info Max length: 50
LastName	Family name.	string	Max length: 50
Email Email address. Type string Additional info Max length: 100
Email	Email address.	string	Max length: 100
LangCode ISO 639-1 language code. If empty the DefaultLanguage from the querystring will be used, if not available the language from the user who created the api key will be used. Type string Additional info Max length: 2
LangCode	ISO 639-1 language code. If empty the DefaultLanguage from the querystring will be used, if not available the language from the user who created the api key will be used.	string	Max length: 2
Phone E.164 phone number. Type string Additional info Max length: 20
Phone	E.164 phone number.	string	Max length: 20
Gender M or F. Type string
Gender	M or F.	string
DateOfBirth Date of birth. Type date Additional info Format as YYYY-MM-DD
DateOfBirth	Date of birth.	date	Format as YYYY-MM-DD
Street Street. Type string Additional info Max length: 50
Street	Street.	string	Max length: 50
HouseNumber House number. Type string Additional info Max length: 6
HouseNumber	House number.	string	Max length: 6
Suite Suite or appartment. Type string Additional info Max length: 4
Suite	Suite or appartment.	string	Max length: 4
PostalCode Postal code. Type string Additional info Max length: 15
PostalCode	Postal code.	string	Max length: 15
City City. Type string Additional info Max length: 50
City	City.	string	Max length: 50
State ISO 3166-2: US State code. Type string Additional info Max length: 2
State	ISO 3166-2: US State code.	string	Max length: 2
Province Province. Type string Additional info Max length: 50
Province	Province.	string	Max length: 50
Country ISO 3166-1 Country Code. Type string Additional info Max length: 2
Country	ISO 3166-1 Country Code.	string	Max length: 2
CustomField1 Your own metadata which can be used as a variable in the surveys, display logic and reporting. Type string Additional info Max length: 256
CustomField1	Your own metadata which can be used as a variable in the surveys, display logic and reporting.	string	Max length: 256
CustomField2 Type string Additional info Max length: 256
CustomField2		string	Max length: 256
CustomField3 Type string Additional info Max length: 256
CustomField3		string	Max length: 256
CustomField4 Type string Additional info Max length: 256
CustomField4		string	Max length: 256
CustomField5 Type string Additional info Max length: 256
CustomField5		string	Max length: 256
CustomField6 Type string Additional info Max length: 256
CustomField6		string	Max length: 256
CustomField7 Type string Additional info Max length: 256
CustomField7		string	Max length: 256
CustomField8 Type string Additional info Max length: 256
CustomField8		string	Max length: 256
CustomField9 Type string Additional info Max length: 256
CustomField9		string	Max length: 256
CustomField10 Type string Additional info Max length: 256
CustomField10		string	Max length: 256
CustomField11 Type string Additional info Max length: 256
CustomField11		string	Max length: 256
CustomField12 Type string Additional info Max length: 256
CustomField12		string	Max length: 256
CustomField13 Type string Additional info Max length: 256
CustomField13		string	Max length: 256
CustomField14 Type string Additional info Max length: 256
CustomField14		string	Max length: 256
CustomField15 Type string Additional info Max length: 256
CustomField15		string	Max length: 256
CustomField16 Type string Additional info Max length: 256
CustomField16		string	Max length: 256
CustomField17 Type string Additional info Max length: 256
CustomField17		string	Max length: 256
CustomField18 Type string Additional info Max length: 256
CustomField18		string	Max length: 256
CustomField19 Type string Additional info Max length: 256
CustomField19		string	Max length: 256
CustomField20 Type string Additional info Max length: 256
CustomField20		string	Max length: 256

Sample:

{
  "DateToBeMailed": "2025-11-03T12:55:30.6632288Z",
  "DateToExpire": "2025-11-03T12:55:30.6632288Z",
  "FirstName": "John",
  "LastName": "Doe",
  "Email": "john.doe@mail.com",
  "LangCode": "en",
  "Phone": "+1-202-555-0117",
  "Gender": "M",
  "DateOfBirth": "2025-11-03T12:55:30.6632288Z",
  "Street": "Main Street",
  "HouseNumber": "123",
  "Suite": "B",
  "PostalCode": "98765-4321",
  "City": "Anytown",
  "State": "CA",
  "Province": "California",
  "Country": "US",
  "CustomField1": "sample string 1",
  "CustomField2": "sample string 2",
  "CustomField3": "sample string 3",
  "CustomField4": "sample string 4",
  "CustomField5": "sample string 5",
  "CustomField6": "sample string 6",
  "CustomField7": "sample string 7",
  "CustomField8": "sample string 8",
  "CustomField9": "sample string 9",
  "CustomField10": "sample string 10",
  "CustomField11": "sample string 11",
  "CustomField12": "sample string 12",
  "CustomField13": "sample string 13",
  "CustomField14": "sample string 14",
  "CustomField15": "sample string 15",
  "CustomField16": "sample string 16",
  "CustomField17": "sample string 17",
  "CustomField18": "sample string 18",
  "CustomField19": "sample string 19",
  "CustomField20": "sample string 20"
}

Sample:

<NewContact xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <City>Anytown</City>
  <Country>US</Country>
  <CustomField1>sample string 1</CustomField1>
  <CustomField10>sample string 10</CustomField10>
  <CustomField11>sample string 11</CustomField11>
  <CustomField12>sample string 12</CustomField12>
  <CustomField13>sample string 13</CustomField13>
  <CustomField14>sample string 14</CustomField14>
  <CustomField15>sample string 15</CustomField15>
  <CustomField16>sample string 16</CustomField16>
  <CustomField17>sample string 17</CustomField17>
  <CustomField18>sample string 18</CustomField18>
  <CustomField19>sample string 19</CustomField19>
  <CustomField2>sample string 2</CustomField2>
  <CustomField20>sample string 20</CustomField20>
  <CustomField3>sample string 3</CustomField3>
  <CustomField4>sample string 4</CustomField4>
  <CustomField5>sample string 5</CustomField5>
  <CustomField6>sample string 6</CustomField6>
  <CustomField7>sample string 7</CustomField7>
  <CustomField8>sample string 8</CustomField8>
  <CustomField9>sample string 9</CustomField9>
  <DateOfBirth>2025-11-03T12:55:30.6632288+00:00</DateOfBirth>
  <Email>john.doe@mail.com</Email>
  <FirstName>John</FirstName>
  <Gender>M</Gender>
  <HouseNumber>123</HouseNumber>
  <LangCode>en</LangCode>
  <LastName>Doe</LastName>
  <Phone>+1-202-555-0117</Phone>
  <PostalCode>98765-4321</PostalCode>
  <Province>California</Province>
  <State>CA</State>
  <Street>Main Street</Street>
  <Suite>B</Suite>
  <DateToBeMailed>2025-11-03T12:55:30.6632288+00:00</DateToBeMailed>
  <DateToExpire>2025-11-03T12:55:30.6632288+00:00</DateToExpire>
</NewContact>

Response information

Response body fields

Name	Description	Type
Meta The metadata such as paging parameters, status code, timestamp,... which are related to this request. Type MetaData
Meta	The metadata such as paging parameters, status code, timestamp,... which are related to this request.	MetaData
Data The actual data returned by the request. Type ContactCreateResult
Data	The actual data returned by the request.	ContactCreateResult
Links HATEOAS related to this object. It wil contain relevant url's such as previous and next page for paged results, create/update/delete action. These url's can be used in your application for the next steps in your application logic. Type Hateoas
Links	HATEOAS related to this object. It wil contain relevant url's such as previous and next page for paged results, create/update/delete action. These url's can be used in your application for the next steps in your application logic.	Hateoas

Response body samples

JSON
XML

Sample:

{
  "Meta": {
    "Status": 1,
    "TotalRowCount": 1,
    "Limit": 1,
    "Offset": 1,
    "TotalPageCount": 1,
    "StartRec": 1,
    "StopRec": 1,
    "Timestamp": "2025-11-03T12:55:30.678991Z",
    "IsFiltered": true
  },
  "Data": {
    "Succeeded": true,
    "FailureMessage": "sample string 2",
    "ContactId": 1
  }
}

Sample:

<Payload xmlns:i="http://www.w3.org/2001/XMLSchema-instance" z:Id="i1" xmlns:z="http://schemas.microsoft.com/2003/10/Serialization/">
  <Data>
    <FailureMessage>sample string 2</FailureMessage>
    <Succeeded>true</Succeeded>
    <ContactId>1</ContactId>
  </Data>
  <Meta>
    <IsFiltered>true</IsFiltered>
    <Limit>1</Limit>
    <Offset>1</Offset>
    <StartRec>1</StartRec>
    <Status>1</Status>
    <StopRec>1</StopRec>
    <Timestamp>2025-11-03T12:55:30.678991+00:00</Timestamp>
    <TotalPageCount>1</TotalPageCount>
    <TotalRowCount>1</TotalRowCount>
  </Meta>
</Payload>

Definition

POST - 3/contacts?surveyId={surveyId}&logComment={logComment}

Request information

Uri parameters

Request body fields

Request body samples

JSON

XML

Response information

Response body fields

Response body samples

JSON

XML