Openscreen API

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
Canada - Canada's Anti-Spam Legislation (CASL)

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

accountIdstringrequired

contactIdstringrequired

firstNamestringrequired

lastNamestringrequired

middleNamestringrequired

nicknamestringrequired

scanCountnumberrequired

appAccountIdstring

appIdstring

cellPhonestring

consentarray of ContactConsent

createdstring

customAttributesobject

emailAddressstring

lastScanLastScan

lastScanProjectNamestring

lastSmsstring

mailingAddressContactMailingAddress

modifiedstring

typestring

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.

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 with ACCEPTED or DECLINED consent statuses
consentType: Filter results with sms, email, data or custom consent types
lastKey: Used to paginate results
limit: 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.

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

cellPhonestring

consentarray of ContactConsent

customAttributesobject

emailAddressstring

firstNamestring

lastNamestring

mailingAddressContactMailingAddress

middleNamestring

nicknamestring

typestring

Returns

Returns a unique contactId once the contact has been created. Throws an error if the projectId is invalid.

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.

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

typestring

Returns

Returns the linked Asset and Project information for the specified Contact.

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.

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

consentedAtstringrequired

consentTypeConsentTyperequired

consentStatusConsentStatus

projectIdstring

urlstring

urlsarray of string

Returns

Returns the newly created Consent Object. Throws an error if the contactId is invalid.

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 remove sms, email, custom or data 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.

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.

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 with ACCEPTED or DECLINED consent statuses
consentType: Filter results with sms, email, data or custom consent types
lastKey: Used to paginate results
limit: 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.

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.

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.

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

cellPhonestring

consentarray of ContactConsent

customAttributesobject

emailAddressstring

firstNamestring

lastNamestring

mailingAddressContactMailingAddress

middleNamestring

nicknamestring

Returns

Returns the updated Contact object. Throws an error if the projectId is invalid.

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

assetNestedAsset

cellPhonestring

consentarray of ContactConsent

customAttributesobject

emailAddressstring

firstNamestring

lastNamestring

mailingAddressContactMailingAddress

middleNamestring

nicknamestring

typestring

Returns

Returns a unique contactId once the contact has been created. Throws an error if the projectId is invalid.

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

contactsarray of NestedContactrequired

Returns

Returns a list of contactIds for the newly created Contacts. Throws an error if the projectId is invalid.

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.

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 with ACCEPTED or DECLINED consent statuses
consentType: Filter results with sms, email, data or custom consent types
lastKey: Used to paginate results
limit: 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.

Returns

Returns a list of contact objects linked to a project. Throws an error if the projectId is invalid.

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

cellPhonestring

consentarray of ContactConsent

customAttributesobject

emailAddressstring

firstNamestring

lastNamestring

mailingAddressContactMailingAddress

middleNamestring

nicknamestring

typestring

Returns

Returns the newly created Contact containing a unique contactId. Throws an error if the scanId is invalid.

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"
  }
}

Contacts

Consent

Cell Phone

Attributes

Functions

Delete Contacts By Account Id

Returns

Get Consent By Account Id

Returns

Get Contacts By Account Id

Returns

Create Contact By Asset Id

Request Object

Returns

Get Contacts By Asset Id

Returns

Link Contact To Asset

Request Object

Returns

Unlink Contact To Asset

Returns

Create Consent By Contact Id

Request Object

Returns

Delete Consent By Contact Id

Returns

Delete Contact

Returns

Get Consent By Contact Id

Returns

Get Contact

Returns

Get Contact Export By Contact Id

Get Scans By Contact Id

Returns

Link Contact To Scan

Returns

Update Contact

Request Object

Returns

Create Contact By Project Id

Request Object

Returns

Create Contacts By Project Id

Request Object

Returns

Delete Contacts By Project Id

Returns

Get Consent By Project Id

Returns

Get Contacts By Project Id

Returns

Create Contact By Scan Id

Request Object

Returns