Contacts
Create and store customer Contacts once a QR code is scanned. Capture customer consent and programmatically send communications via text or email!
As QR Codes are typically scanned by people, it can be helpful to capture information about individuals scanning specific QR Codes. Openscreen provides the native ability to store Contact objects.
Developers may want to have a QR Code direct a user to a form to fill out information for marketing purposes. Openscreen’s Contact object provides a simple way to capture Contact information and correlate these Contacts back to specific projects, Scans or Assets.
Consent
Contact objects have an optional field used to store consent given from the user. The consent field provides visibility of contacts subscribing, unsubscribing, and resubscribing to communications by keeping a record of all previous forms of consent along with a timestamp of when they were given. The last object within the consent array is the most recent consent status that has been added.
As a developer, it is your responsibility to enforce any anti-spam legislation in the region(s) that you operate in.
United States - CAN-SPAM ACT
Cell Phone
Contact cell phone numbers must be input using the E. 164 International Standard for Phone Numbers:
[+][country code][area code][local phone number] Example: +16478225146
Attributes
Functions
- Delete Contacts By Account Id
- Get Consent By Account Id
- Get Contacts By Account Id
- Create Contact By Asset Id
- Get Contacts By Asset Id
- Link Contact To Asset
- Unlink Contact To Asset
- Create Consent By Contact Id
- Delete Consent By Contact Id
- Delete Contact
- Get Consent By Contact Id
- Get Contact
- Get Contact Export By Contact Id
- Get Scans By Contact Id
- Link Contact To Scan
- Update Contact
- Create Contact By Project Id
- Create Contacts By Project Id
- Delete Contacts By Project Id
- Get Consent By Project Id
- Get Contacts By Project Id
- Create Contact By Scan Id
Delete Contacts By Account Id
Deletes all Contacts in an Openscreen Account. You may pass an optional query parameter of phoneNumber
and/or emailAddress
which deletes only the contacts containing the specified values.
Returns
Returns a list of recently deleted contact objects. Throws an error if the accountId is invalid.
1
2
3
4
const deleteContacts = os.account(accountId).contacts().delete()
// Alternatively, you may delete specific phone numbers by:
// deleteContacts = os.delete(accountId).contacts.delete({phoneNumber: '6471234567'})
{
"entityType": "delete_contacts_by_account_id.response_body",
"accountId": "xxxxxxxxxxxxxx",
"contacts": [
{
"emailAddress": "bsmith@test.com",
"modified": "2021-10-14T16:23:06.526Z",
"mailingAddress": {
"country": "Canada",
"postalOrZip": "A1B2C3",
"address": "123 Street",
"provinceOrState": "ON",
"city": "Toronto"
},
"cellPhone": "+14162121212",
"consent": [
{
"consentedAt": "2021-06-20 08:03:00.0",
"url": "https://sidewalkqr.com/123main/consent",
"consented": "accepted"
}
],
"firstName": "Brian",
"contactId": "b5b0cf87-6abf-428d-9e6b-7118af3d27ba",
"lastName": "Smith",
"created": "2021-10-14T16:23:06.526Z"
},
{
"emailAddress": "jd@example.com",
"cellPhone": "+14169414102",
"consent": [
{
"url": "www.example.com",
"consented": "accepted"
}
],
"customAttributes": {},
"created": "2021-10-25T10:10:02.954Z",
"modified": "2021-10-25T10:10:02.954Z",
"mailingAddress": {
"country": "Canada",
"postalOrZip": "M5M2W4",
"address": "1 Example Crescent North",
"provinceOrState": "ON",
"city": "Toronto"
},
"firstName": "Jane",
"contactId": "0d530f7b-08e7-4e63-825b-e713f6a0364c",
"lastName": "Doe"
}
]
}
Get Consent By Account Id
Returns a list of ContactConsent objects associated to an Openscreen Account. ContactConsent objects contain contactId
of the associated Contacts.
This endpoint accepts the following optional query string parameters:
consentStatus
: Filter results withACCEPTED
orDECLINED
consent statusesconsentType:
Filter results withsms
,email
,data
orcustom
consent typeslastKey:
Used to paginate resultslimit:
Limits the number of results fetched up to a maximum of 100 results.
Returns
Returns a ContactConsent objects filtered by query string parameters. Throws an error if the accountId is invalid.
1
2
3
consentByAccount = os.account(accountId).consent().get({
consentType: "ACCEPTED",
})
{
"entityType": "get_consent_by_account_id.response_body",
"accountId": "xxxxxxxxxxxxxxxxxx",
"consent": [{
"accountName": "My Company",
"consentStatus": "ACCEPTED",
"consented": true,
"consentType": "SMS",
"consentedAt": "2021-06-20 08:03:00.0",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["my-app.com/terms-and-conditions"],
},
{
"accountName": "My Company",
"consentStatus": "ACCEPTED",
"consented": true,
"consentType": "SMS",
"consentedAt": "2021-08-21 09:05:00.0",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["my-app.com/terms-and-conditions"],
},
{
"accountName": "My Company",
"consentStatus": "ACCEPTED",
"consented": true,
"consentType": "SMS",
"consentedAt": "2021-03-12 22:03:00.0",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["my-app.com/terms-and-conditions"],
},
]
}
Get Contacts By Account Id
Retrieves Contacts associated to an Openscreen Account.
The number of Contacts retrieved can be modified using the 'limit' field for up to 100 per request. The next batch of Contacts can be retrieved using the 'lastKey' field - a hashed key that points to the last object of the current batch.
Returns
Returns a list of Contact objects associated to an Openscreen accountId. Throws an error if the accountId is invalid.
1
const contactsByAccount = await os.account(accountId).contacts().get();
{
"entityType": "get_contacts_by_account_id.response_body",
"accountId": "xxxxxxxxxxxxxxxxxxxxxxxx",
"lastKey": "xxxxxxxxxxxx",
"numberOfContacts": 2,
"contacts": [
{
"emailAddress": "bsmith@test.com",
"modified": "2021-10-14T16:23:06.526Z",
"mailingAddress": {
"country": "Canada",
"postalOrZip": "A1B2C3",
"address": "123 Street",
"provinceOrState": "ON",
"city": "Toronto"
},
"cellPhone": "+14162121212",
"consent": [
{
"consentedAt": "2021-06-20 08:03:00.0",
"url": "https://sidewalkqr.com/123main/consent",
"consented": "accepted"
}
],
"firstName": "Brian",
"contactId": "b5b0cf87-6abf-428d-9e6b-7118af3d27ba",
"lastName": "Smith",
"created": "2021-10-14T16:23:06.526Z"
},
{
"emailAddress": "jd@example.com",
"cellPhone": "+14169414102",
"consent": [
{
"url": "www.example.com",
"consented": "accepted"
}
],
"customAttributes": {},
"created": "2021-10-25T10:10:02.954Z",
"modified": "2021-10-25T10:10:02.954Z",
"mailingAddress": {
"country": "Canada",
"postalOrZip": "M5M2W4",
"address": "1 Example Crescent North",
"provinceOrState": "ON",
"city": "Toronto"
},
"firstName": "Jane",
"contactId": "0d530f7b-08e7-4e63-825b-e713f6a0364c",
"lastName": "Doe"
}
]
}
Create Contact By Asset Id
Creates a new Contact within the given Asset. Contact objects have an optional field used to store consent given from the user. The consent field provides visibility of contacts subscribing, unsubscribing, and resubscribing to communications by keeping a record of all previous forms of consent along with a timestamp of when they were given. The last object within the consent array is the most recent consent status that has been added. Contact cell phone numbers must be input using the E. 164 International Standard for Phone Numbers.
Request Object
Returns
Returns a unique contactId once the contact has been created. Throws an error if the projectId is invalid.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
const contact = await os.asset(assetId).contacts().create({
firstName: "Brian",
lastName: "Smith",
emailAddress: "bsmith@test.com",
mailingAddress: {
address: "123 Street",
city: "Toronto",
provinceOrState: "ON",
country: "Canada",
postalOrZip: "A1B2C3"
},
consent: [{url: "https://sidewalkqr.com/123main/consent", consentedAt: "2021-06-20 08:03:00.0", consented: true}],
cellPhone: "+14162121212",
});
{
"entityType": "create_contact_by_asset_id.response_body",
"assetId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"contact": {
"entityType": "app.contact",
"contactId": "c162a031-2d4a-462e-a12f-c4b7e6d870e5",
"emailAddress": "bsmith@test.com",
"cellPhone": "+12892213345",
"firstName": "Brian",
"middleName": "",
"lastName": "Smith",
"nickname": "",
"mailingAddress": {
"entityType": "app.contact-mailing-address",
"address": "123 Street",
"city": "Toronto",
"provinceOrState": "ON",
"postalOrZip": "A1B2C3",
"country": "Canada"
},
"consent": [
{
"entityType": "app.contact-consent",
"consented": true,
"consentedAt": "2021-06-20T08:03:00.000Z",
"url": "https://sidewalkqr.com/123main/consent"
}
]
},
"projectContact": {
"entityType": "app.project-contact",
"projectId": "a76adcf6-002d-40e0-b156-7f2e2d82733b",
"contactId": "c162a031-2d4a-462e-a12f-c4b7e6d870e5"
},
"contactPhone": {
"entityType": "app.contact-phone",
"phone": "+12892213345",
"projectId": "a76adcf6-002d-40e0-b156-7f2e2d82733b",
"contactId": "c162a031-2d4a-462e-a12f-c4b7e6d870e5"
},
"contactEmail": {
"entityType": "app.contact-email",
"email": "bsmith@test.com",
"projectId": "a76adcf6-002d-40e0-b156-7f2e2d82733b",
"contactId": "c162a031-2d4a-462e-a12f-c4b7e6d870e5"
}
}
Get Contacts By Asset Id
Retrieves Contacts linked to an Asset. A valid assetId must be supplied in the request.
Returns
Returns a list of contact objects linked to an Asset. Throws an error if the assetId is invalid.
1
const contacts = await os.asset(assetId).contacts().get();
{
"entity_type": "get_contacts_by_asset_id.response_body",
"asset_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"asset_contacts": [{
"asset_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"contact_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"asset_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"contact_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}]
"number_of_contacts": 2,
"contacts": [
{
"entity_type": "app.contact",
"email_address": "bsmith@test.com",
"modified": "2021-10-14_t16:23:06.526_z",
"mailing_address": {
"country": "Canada",
"postal_or_zip": "A1B2C3",
"address": "123 Street",
"province_or_state": "ON",
"city": "Toronto"
},
"cell_phone": "+14162121212",
"consent": [
{
"consented_at": "2021-06-20 08:03:00.0",
"url": "https://sidewalkqr.com/123main/consent",
"consented": "true"
}
"first_name": "Brian",
"contact_id": "b5b0cf87-6abf-428d-9e6b-7118af3d27ba",
"last_name": "Smith",
"created": "2021-10-14_t16:23:06.526_z"
},
{
"entity_type": "app.contact",
"email_address": "jd@example.com",
"cell_phone": "+14169414102",
"consent": [
{
"url": "www.example.com",
"consented": "true"
}
"custom_attributes": {},
"created": "2021-10-25_t10:10:02.954_z",
"modified": "2021-10-25_t10:10:02.954_z",
"mailing_address": {
"country": "Canada",
"postal_or_zip": "M5M2M4",
"address": "123 Eglinton Avenue",
"province_or_state": "ON",
"city": "Toronto"
},
"first_name": "Jane",
"contact_id": "0d530f7b-08e7-4e63-825b-e713f6a0364c",
"last_name": "Doe"
}
]
}
Link Contact To Asset
Links a pre-existing Contact to an Asset.
Request Object
Returns
Returns the linked Asset and Project information for the specified Contact.
1
const linkContactToAsset = await os.asset(assetId).contact(contactId).link();
{
"entity_type": "link_contact_to_asset.response_body",
"assetContact": {
"assetId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"contactId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
"projectContact": {
"projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}
Unlink Contact To Asset
Unlinks a pre-existing Contact and Asset. Contact will continue to be linked to its Project.
Returns
Upon success, the Contact and Asset are unlinked. There is no response for this call. Throws an error if the assetId and/or contactId are invalid.
1
const unlinkContactToAsset = await os.asset(assetId).contact(contactId).unlink();
''
Create Consent By Contact Id
Creates a new Consent object for a Contact. By default, Consent is captured at an account level. Specifying a valid projectId in the request will limit the scope of the Consent to the project level.
As the application developer, it is your responsibility to ensure a valid Consent object for each Contact before any communication is sent.
Request Object
Returns
Returns the newly created Consent Object. Throws an error if the contactId is invalid.
Related guide: Adding Contacts and Consent to your Project.
1
2
3
4
5
6
7
const createConsent = await os.contact(contactId).consent().create({
consentStatus: "ACCEPTED",
consentType: "SMS",
consentedAt: "2021-08-21 09:05:00.0",
projectId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
url: ["myapp.com/terms-and-conditions", "myapp2.com/terms-and-conditions"]
});
{
"entityType": "create_consent_by_contact_id.response_body",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"consent": {
"consentStatus": "ACCEPTED",
"consented": true,
"consentType": "SMS",
"consentedAt": "2021-08-21 09:05:00.0",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["myapp.com/terms-and-conditions", "myapp2.com/terms-and-conditions"]
}
}
Delete Consent By Contact Id
Removes the Consent entities for a Contact. This call accepts the following query string parameters:
consentStatus
: Allows you to remove 'Accepted' or 'Declined' consent.consentType
: Allows you to removesms, email, custom
ordata
consent types.projectId: If this parameter is present, the consent is only removed for the specified project.
Returns
Returns the list of deleted Consent objects for the ContactId. Throws an error if the contactId is invalid.
1
2
3
4
const deleteContactConsent = await os.contact(contactId).consent().delete({
consentType: 'SMS',
consentStatus: 'ACCEPTED'
})
{
"entityType": "delete_consent_by_contact_id.response_body",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"consent": [{
"accountName": "My Company",
"consentStatus": "ACCEPTED",
"consented": true,
"consentType": "SMS",
"consentedAt": "2021-06-20 08:03:00.0",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["my-app.com/terms-and-conditions"],
},
{
"accountName": "My Company",
"consentStatus": "ACCEPTED",
"consented": true,
"consentType": "SMS",
"consentedAt": "2021-08-21 09:05:00.0",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["my-app.com/terms-and-conditions"],
}
]
}
Delete Contact
Deletes a Contact. A valid contactId must be passed in the request.
Returns
Returns the contact object for the deleted contactId. Throws an error if the contactId is invalid.
1
const deleteContact = await os.contact(contactId).delete();
{
"contact": {
"contactId": "4d8784b9-7867-4b18-a090-5f3715e7ad85",
"firstName": "Brian",
"lastName": "Smith",
"emailAddress": "bsmith@test.com",
"mailingAddress": {
"address": "123 Street",
"city": "Toronto",
"provinceOrState": "ON",
"country": "Canada",
"postalOrZip": "A1B2C3"
},
"consent": {
"url": "https://sidewalkqr.com/123main/consent",
"consentedAt": "2021-06-20 08:03:00.0",
"consented": "true"
},
"cellPhone": "+14162121212"
}
}
Get Consent By Contact Id
Returns the Consent provided by an Openscreen Contact. The results can be filtered using the following query string parameters:
consentStatus
: Filter results withACCEPTED
orDECLINED
consent statusesconsentType:
Filter results withsms
,email
,data
orcustom
consent typeslastKey:
Used to paginate resultslimit:
Limits the number of results fetched up to a maximum of 100 results.
Returns
Returns a list of Consent objects captured against a Contact. Throws an error if the contactId is invalid.
1
2
3
contactConsent = await os.contact(contactId).consent().get({
consentType: "ACCEPTED"
})
{
"entityType": "get_consent_by_account_id.response_body",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"consent": [{
"accountName": "My Company",
"consentStatus": "ACCEPTED",
"consented": true,
"consentedAt": "2021-06-20 08:03:00.0",
"consentType": "SMS",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["my-app.com/terms-and-conditions"],
},
{
"accountName": "My Company",
"consentStatus": "ACCEPTED",
"consented": true,
"consentedAt": "2021-08-21 09:05:00.0",
"consentType": "SMS",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["my-app2.com/terms-and-conditions"],
},
{
"accountName": "My Company",
"consentStatus": "ACCEPTED",
"consented": true,
"consentedAt": "2021-03-12 22:03:00.0",
"consentType": "SMS",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["my-app3.com/terms-and-conditions"],
},
]
}
Get Contact
Retrieves details of a Contact, including their consent object.
Returns
Returns the contact object for the specified contactId. Throws an error if the contactId is invalid.
1
const contact = await os.contact(contactId).get();
{
"contact": {
"contactId": "4d8784b9-7867-4b18-a090-5f3715e7ad85",
"firstName": "Brian",
"lastName": "Smith",
"emailAddress": "bsmith@test.com",
"mailingAddress": {
"address": "123 Street",
"city": "Toronto",
"provinceOrState": "ON",
"country": "Canada",
"postalOrZip": "A1B2C3"
},
"consent": {
"url": "https://sidewalkqr.com/123main/consent",
"consentedAt": "2021-06-20 08:03:00.0",
"consented": "accepted"
},
"cellPhone": "+14162121212"
}
}
Get Contact Export By Contact Id
Get Scans By Contact Id
Returns all the scans linked to an Openscreen Contact.
Returns
Returns a list of Scan objects linked to an Openscreen Contact. Throws an error if the contactId is invalid.
1
scansByContact = await os.contact(contactId).scans().get()
{
"entityType": "get_scans_by_contact_id.response_body",
"scans": [{
"scanTime": "2021-10-14T15:35:41.115Z",
"locationLongitude": "-114.07640",
"engineName": "Blink",
"locationString": "Calgary, Alberta, Canada",
"locationRegionName": "Alberta",
"locationCountryName": "Canada",
"locationTimeZone": "America/Edmonton",
"modified": "2021-10-14T15:35:42.474Z",
"deviceModel": "SM-G973W",
"deviceType": "mobile",
"browserVersion": "15.0",
"scanId": "c262c53e-3ec0-4f48-823e-de5539dd85dc",
"deviceVendor": "Samsung",
"osName": "Android",
"locationCityName": "Calgary",
"qrCodeId": "b5ca08a8-3ce5-4c33-8fca-605550f078aa",
"engineVersion": "90.0.4430.210",
"locationPostalCode": "T2R",
"entity": "app.scan",
"ipAddress": "xx.xxx.xxx.xxx",
"locationRegionCode": "AB",
"created": "2021-10-14T15:35:42.474Z",
"osVersion": "11",
"userAgent": "Mozilla/5.0 (Linux; Android 11; SAMSUNG SM-G973W) AppleWebKit/537.36 (KHTML, like Gecko) SamsungBrowser/15.0 Chrome/90.0.4430.210 Mobile Safari/537.36",
"locationLatitude": "51.04060",
"projectId": "a76adcf6-002d-40e0-b156-7f2e2d82733b",
"browserName": "Samsung Browser",
"locationCountryCode": "CA",
"assetId": "ef43b29d-55c5-48d4-b70c-80c1c145fe14",
"assetName": "123 Main Street"
}]
}
Link Contact To Scan
Links a Contact Object to a QR Code Scan. It is recommended that you call this method after a Contact is created. Each time you see that an existing Contact scans a QR code, you can link that scan to the Contact. Over time, this will allow you to record history of all QR code scans from a Contact.
If you use 'CreateContactByScanId
', you do not need to call this method, your Contact will be automatically linked to the scanId passed in the request.
Returns
Returns the asset, project and scan information associated to a Contact. Throws an error if the scanId or the contactId are invalid.
1
const linkContactToScan = await os.contact(contactId).scan(scanId).link();
{
"entityType": "link_contact_to_scan_id.response_body",
"assetId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"assetName": "123 Main Street",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"scanId": "xxxxxxxxxxxxx-xxxxxxxxxxx",
}
Update Contact
Updates an existing Contact. This update clears the existing field(s) and updates to the new inputted value(s), with the exception of the consent object. When consent is updated, a new consent object is appended to the consent array. This provides history of every previous consent status.
Request Object
Returns
Returns the updated Contact object. Throws an error if the projectId is invalid.
1
2
3
4
const contact = await os.contact(contactId).update({
firstName: "Taylor",
consent: [{url: "https://sidewalkqr.com/123main/consent", consentedAt: "2021-09-21 09:03:00.0", consented: false}]
});
{
"contact": {
"emailAddress": "bsmith@test.com",
"modified": "2021-09-21T12:59:34.078Z",
"mailingAddress": {
"country": "Canada",
"postalOrZip": "A1B2C3",
"address": "123 Street",
"provinceOrState": "ON",
"city": "Toronto"
},
"cellPhone": "+14162121212",
"consent": [
{
"consentedAt": "2021-06-20 08:03:00.0",
"url": "https://sidewalkqr.com/123main/consent",
"consented": "true"
},
{
"consentedAt": "2021-09-21 09:03:00.0",
"url": "https://sidewalkqr.com/123main/consent",
"consented": "false"
}
],
"firstName": "Taylor",
"contactId": "e9618422-c7e6-4e91-a909-d37cd981c888",
"lastName": "Smith",
"created": "2021-09-21T12:58:15.608Z"
}
}
Create Contact By Project Id
Creates a new Contact and appends it to a Project. Contacts store information on an individual and can be associated with an Asset. This request also allows you to create an Asset and link the contact to it.
Request Object
Returns
Returns a unique contactId once the contact has been created. Throws an error if the projectId is invalid.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
const contact = await os.project(projectId).contacts().create({
firstName: "Brian",
lastName: "Smith",
emailAddress: "bsmith@test.com",
mailingAddress: {
address: "123 Street",
city: "Toronto",
provinceOrState: "ON",
country: "Canada",
postalOrZip: "A1B2C3"
},
consent: [{url: "https://sidewalkqr.com/123main/consent", consentedAt: "2021-06-20 08:03:00.0", consented: true}],
cellPhone: "+14162121212"
});
{
"entityType": "create_contact_by_project_id.response_body",
"projectId": "a76adcf6-002d-40e0-b156-7f2e2d82733b",
"contact": {
"entityType": "app.contact",
"contactId": "c162a031-2d4a-462e-a12f-c4b7e6d870e5",
"emailAddress": "bsmith@test.com",
"cellPhone": "+12892213345",
"firstName": "Brian",
"middleName": "",
"lastName": "Smith",
"nickname": "",
"mailingAddress": {
"entityType": "app.contact-mailing-address",
"address": "123 Street",
"city": "Toronto",
"provinceOrState": "ON",
"postalOrZip": "A1B2C3",
"country": "Canada"
},
"consent": [
{
"entityType": "app.contact-consent",
"consented": true,
"consentedAt": "2021-06-20T08:03:00.000Z",
"url": "https://sidewalkqr.com/123main/consent"
}
]
},
"projectContact": {
"entityType": "app.project-contact",
"projectId": "a76adcf6-002d-40e0-b156-7f2e2d82733b",
"contactId": "c162a031-2d4a-462e-a12f-c4b7e6d870e5"
},
"contactPhone": {
"entityType": "app.contact-phone",
"phone": "+12892213345",
"projectId": "a76adcf6-002d-40e0-b156-7f2e2d82733b",
"contactId": "c162a031-2d4a-462e-a12f-c4b7e6d870e5"
},
"contactEmail": {
"entityType": "app.contact-email",
"email": "bsmith@test.com",
"projectId": "a76adcf6-002d-40e0-b156-7f2e2d82733b",
"contactId": "c162a031-2d4a-462e-a12f-c4b7e6d870e5"
}
}
Create Contacts By Project Id
Creates Contacts in bulk which are linked to a Project. These Contacts do not necessarily originate from a QR Code scan. This can be useful when importing existing contacts from a Customer Relationship Management (CRM) tool or equivalent. This request also allows a user to create a new Asset and a QR Code.
Request Object
Returns
Returns a list of contactIds for the newly created Contacts. Throws an error if the projectId is invalid.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
const contacts = await os.project(projectId).contactsBatch().create({
firstName: "Brian",
lastName: "Smith",
emailAddress: "bsmith@test.com",
mailingAddress: {
address: "123 Street",
city: "Toronto",
provinceOrState: "ON",
country: "Canada",
postalOrZip: "A1B2C3"
},
consent: [{url: "https://sidewalkqr.com/123main/consent", consentedAt: "2021-06-20 08:03:00.0", consented: true}],
cellPhone: "+14162121212",
asset: [{
assetId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
name: "My first Asset",
description: "123 Main Street",
qrCodes: [{
dynamicRedirectType: "NO_SCAN_ID",
intent: "www.openscreen.com",
intentState: { state: 'Pending Ownership' },
intentType: "DYNAMIC_REDIRECT",
locatorKeyType: "SHORT_URL"
}]
},
{
firstName: "John",
lastName: "Smith",
emailAddress: "johnsmith@test.com",
mailingAddress: {
address: "1234 Baker Street",
city: "Toronto",
provinceOrState: "ON",
country: "Canada",
postalOrZip: "X1Y2Z3"
},
consent: [{url: "https://sidewalkqr.com/123main/consent", consentedAt: "2021-06-20 08:05:00.0", consented: true}],
cellPhone: "+14161234567"
}
});
{
"entityType": "create_contacts_by_project_id.response_body",
"projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"numberOfContacts": 2,
"contacts": ["xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"]
}
Delete Contacts By Project Id
Deletes all contacts associated to an Openscreen Project. You may pass an optional query parameter of phoneNumber
and/or emailAddress
which deletes only the contacts containing the specified values.
Returns
Returns a list of recently deleted contact objects. Throws an error if the accountId is invalid.
1
2
3
4
const deleteContacts = os.account(projectId).contacts().delete()
// Alternatively, you may delete specific phone numbers by:
// deleteProjectContacts = os.delete(projectId).contacts.delete({phoneNumber: '6471234567'})
{
"entityType": "delete_contacts_by_project_id.response_body",
"accountId": "xxxxxxxxxxxxxx",
"contacts": [
{
"emailAddress": "bsmith@test.com",
"modified": "2021-10-14T16:23:06.526Z",
"mailingAddress": {
"country": "Canada",
"postalOrZip": "A1B2C3",
"address": "123 Street",
"provinceOrState": "ON",
"city": "Toronto"
},
"cellPhone": "+14162121212",
"consent": [
{
"consentedAt": "2021-06-20 08:03:00.0",
"url": "https://sidewalkqr.com/123main/consent",
"consented": "accepted"
}
],
"firstName": "Brian",
"contactId": "b5b0cf87-6abf-428d-9e6b-7118af3d27ba",
"lastName": "Smith",
"created": "2021-10-14T16:23:06.526Z"
},
{
"emailAddress": "jd@example.com",
"cellPhone": "+14169414102",
"consent": [
{
"url": "www.example.com",
"consented": "accepted"
}
],
"customAttributes": {},
"created": "2021-10-25T10:10:02.954Z",
"modified": "2021-10-25T10:10:02.954Z",
"mailingAddress": {
"country": "Canada",
"postalOrZip": "M5M2W4",
"address": "1 Example Crescent North",
"provinceOrState": "ON",
"city": "Toronto"
},
"firstName": "Jane",
"contactId": "0d530f7b-08e7-4e63-825b-e713f6a0364c",
"lastName": "Doe"
}
]
}
Get Consent By Project Id
Returns a list of ContactConsent objects associated to an Openscreen Project. ContactConsent objects contain contactId
of the associated Contacts.
This endpoint accepts the following optional query string parameters:
consentStatus
: Filter results withACCEPTED
orDECLINED
consent statusesconsentType:
Filter results withsms
,email
,data
orcustom
consent typeslastKey:
Used to paginate resultslimit:
Limits the number of results fetched up to a maximum of 100 results.
Returns
Returns a ContactConsent objects filtered by query string parameters. Throws an error if the projectId is invalid.
1
2
3
consentByProject = os.project(projectId).consent().get({
consentType: "ACCEPTED",
})
{
"entityType": "get_consent_by_account_id.response_body",
"projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"consent": [{
"accountName": "My Company",
"consentStatus": "ACCEPTED",
"consented": true,
"consentType": "SMS",
"consentedAt": "2021-06-20 08:03:00.0",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["my-app.com/terms-and-conditions"],
},
{
"accountName": "My Company",
"consentStatus": "ACCEPTED",
"consented": true,
"consentType": "SMS",
"consentedAt": "2021-08-21 09:05:00.0",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["my-app.com/terms-and-conditions"],
},
{
"accountName": "My Company",
"consentStatus": "ACCEPTED",
"consented": true,
"consentType": "SMS",
"consentedAt": "2021-03-12 22:03:00.0",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxxx",
"url": ["my-app.com/terms-and-conditions"],
},
]
}
Get Contacts By Project Id
Retrieves Contacts in the specified Project. Each Contact contains the timestamp when the consent was captured.
The number of Contacts retrieved can be modified using the 'limit' field for up to 100 per request. The next batch of Contacts can be retrieved using the 'lastKey' field - a hashed key that points to the last object of the current batch.
Returns
Returns a list of contact objects linked to a project. Throws an error if the projectId is invalid.
1
const contacts = await os.project(projectId).contacts().get();
{
"projectId": "a76adcf6-002d-40e0-b156-7f2e2d82733b",
"numberOfContacts": 2,
"contacts": [
{
"emailAddress": "bsmith@test.com",
"modified": "2021-10-14T16:23:06.526Z",
"mailingAddress": {
"country": "Canada",
"postalOrZip": "A1B2C3",
"address": "123 Street",
"provinceOrState": "ON",
"city": "Toronto"
},
"cellPhone": "+14162121212",
"consent": [
{
"consentedAt": "2021-06-20 08:03:00.0",
"url": "https://sidewalkqr.com/123main/consent",
"consented": "accepted"
}
],
"firstName": "Brian",
"contactId": "b5b0cf87-6abf-428d-9e6b-7118af3d27ba",
"lastName": "Smith",
"created": "2021-10-14T16:23:06.526Z"
},
{
"emailAddress": "jd@example.com",
"cellPhone": "+14169414102",
"consent": [
{
"url": "www.example.com",
"consented": "accepted"
}
],
"customAttributes": {},
"created": "2021-10-25T10:10:02.954Z",
"modified": "2021-10-25T10:10:02.954Z",
"mailingAddress": {
"country": "Canada",
"postalOrZip": "M5M2W4",
"address": "1 Example Crescent North",
"provinceOrState": "ON",
"city": "Toronto"
},
"firstName": "Jane",
"contactId": "0d530f7b-08e7-4e63-825b-e713f6a0364c",
"lastName": "Doe"
}
]
}
Create Contact By Scan Id
Creates a new Contact that is associated to a specific Scan using the scanId.
Request Object
Returns
Returns the newly created Contact containing a unique contactId. Throws an error if the scanId is invalid.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
const contactByScanId = await os.scan(scanId).contacts().create({
firstName: "Brian",
lastName: "Smith",
emailAddress: "bsmith@test.com",
mailingAddress: {
address: "123 Street",
city: "Toronto",
provinceOrState: "ON",
country: "Canada",
postalOrZip: "A1B2C3"
},
consent: [{url: "https://sidewalkqr.com/123main/consent", consentedAt: "2021-06-20 08:03:00.0", consented: true}],
cellPhone: "+14162121212",
});
{
"entityType": "create_contact_by_scan_id.response_body",
"assetId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"asset": {
"entityType": "app.asset",
"created": "2022-07-05T13:59:46.000Z",
"modified": "2022-07-05T16:18:13.000Z",
"assetId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"name": "123 Main Street Sign",
"description": "Listing for 123 Main Street",
"scanCount": 1,
"dynamicQrCodeCount": 1,
"staticQrCodeCount": 0,
"lastScanId": "xxxxxxxxxxxxx-xxxxxxxxxxx"
},
"contact": {
"entityType": "app.contact",
"created": "2022-07-05T16:18:37.000Z",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",,
"accountId": "xxxxxxxxxxxxxx",
"emailAddress": "bsmith@test.com",
"cellPhone": "+16475554181",
"firstName": "Brian",
"middleName": "",
"lastName": "Smith"
"emailAddress": "bsmith@test.com",
"cellPhone": "+14162121212",
"nickname": "",
"mailingAddress": {
"address": "123 Street",
"city": "Toronto",
"provinceOrState": "ON",
"country": "Canada",
"postalOrZip": "A1B2C3"
},
"consent": [{"url": "https://sidewalkqr.com/123main/consent", "consented_at": "2021-06-20 08:03:00.0", "consented": true}],
"customAttributes": {}
},
"projectContact": {
"entityType": "app.project_contact",
"projectId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
},
"assetContact": {
"entityType": "app.asset_contact",
"assetId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"type": ""
},
"scanContact": {
"entityType": "app.scan_contact",
"scanId": "xxxxxxxxxxxxx-xxxxxxxxxxx",
"contactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}
}