Create a Session

Here is a simple flow needed to get the redirect URL for the check-in:

Endpoints

POST /session/create

Parameters

• groupID: This is the group ID of the group that the user is associated with. Note that you have to create a group before the first check-in.
• groupKey: The group key is associated with the group that you created.
• userIdentifier: For the first session, you need to provide the user email. For subsequent sessions, you will have to provide the user ID. The user ID will be provided in the response of a session creation and through a webhook.
• returnURL: This is the URL that the user will be redirected to when their check-in is completed. Please make sure the redirect URL is an HTTPS endpoint as we will not redirect to HTTP or localhost.

Example Call

JavaScript

await fetch("https://api.okaya.me/session/create", {
  method: "POST",
  headers: {
    "x-api-key": "YOUR API KEY",
  },
  body: JSON.stringify({
    groupID: 123456,
    groupKey: "YOUR GROUP KEY",
    userIdentifier: "THE PARTICIPANT EXTERNAL ID OR THE PARTICIPANT EMAIL",
    returnURL: "https://www.mysiteredirect.com",
  }),
});

Python

import requests

requests.post("https://api.okaya.me/session/create",
    headers={
        "x-api-key": "YOUR_API_KEY"
    },
    json={
        "groupID": 123456,
        "groupKey": "YOUR GROUP KEY",
        "userIdentifier": "THE PARTICIPANT EXTERNAL ID OR THE PARTICIPANT EMAIL",
        "returnURL": "https://www.mysiteredirect.com",
    }
).json()

cURL

curl --location --request POST "https://api.okaya.me/session/create" \
--header "x-api-key: YOUR_API_KEY" \
--header "Content-Type: application/json" \
--data-raw '{
    "groupID": 123456,
    "groupKey": "YOUR GROUP KEY",
    "userIdentifier": "THE PARTICIPANT EXTERNAL ID OR THE PARTICIPANT EMAIL",
    "returnURL": "https://www.mysiteredirect.com"
}'

Example Response

200

{
  "success": true,
  "message": "Redirect URL generated successfully.",
  "userIdentifier": "ok_123dsf",
  "redirectUrl": "https://mindcheck.okaya.me/integrationUser/embedded-mhci-checki...",
  "sessionID": "abcd1234"
}

400

Invalid 'groupID'

{ "error": "You are missing the path parameter groupID" | "groupID must be a number" }

Invalid 'groupKey'

{ "error": "You are missing the body parameter groupKey" | "groupKey must be a string" }

Invalid 'userIdentifier'

{ "error": "You are missing the body parameter userIdentifier" | "userIdentifier must be a string" }

Invalid 'returnURL'

{ "error": "You are missing the body parameter returnURL" | "returnURL must be a string" }

Invalid user information

{ "error": "We require email for new users or ok_ id for existing users" }

User not in group

{ "error": "User ok_participant1 is not part of group 123456" }

User already exists

{ "error": "This user already exists for the email and groupID provided, their externalID is ok_participant1" }

{ "error": "Group not found" }

401: Unauthorized