This guide will advise any integrator on how to use parts of the Foxo B2B API to login/register users from their platform and do operations on their behalf.
\nAfter successful authentication with the API an integrator can use their platform or application to send their users to a co-branded Foxo registration or login page to instantly connect them to the Foxo network. The process is roughly like this:
\nUser Exists API operation.; in the URL (examples below). Note in order to show a co-branded UI the integration parameter is required. A custom_id parameter can be provided in case the API User needs to map ID's from users in their system to the Foxo Users. A optional callback parameter with an endpoint accepting JSON can be provided if the API User wants to track user creation in realtime.ICON). The users having which have an integration setup with that provider can then be listed by the B2B API User using the List integration users endpoint. This will return those users user_uid's beside basic profile information and their custom_id's (if provided during login/registration). The user_uids can then be used to execute all the operations listed in https://github.com/foxo-tech/foxo-integration-api on the users behalf.This guide provides details about how to initialise an (outbound) Foxo guest chat and allowing a user to skip the One-time Password (OTP) validation and pre-populate the chat with messages/subject step while doing so.
\nAfter successful authentication with the API an integrator can use the provided details to start a Foxo guest chat with a Foxo team for a given user of their platform and pre-populate the chat as well as other information.
\nIn order to start the process, an integrator has to make an API call to the Create Outbound guest case/chat API endpoint and provide all necessary details. Upon successful response an access token is returned from that API endpoint. Note that a guest case token expires after first use. That means that each time a new guest chat/case has to be started a new B2B API call has to be done beforehand and the new link has to be used.
The access token allows a user to sign into Foxo guest chat without having to provide an OTP (one time password). Once the login is successful the guest chat is automatically created with the parameters provided (guest chat subject and initial messages).
\nThe conditions to skip OTP validation are the following when using the outbound guest link created by the B2B API:
\n* The user provides a new email address which has never been used with Foxo or Foxo Guest when logging in to Guest Chat
* The user provides an existing email address which he/she signed in with previously and the user identifier provided via B2B API either matches that email (`email` identifier) or was previously associated with that user (`session_id` / user_id / ip_address )identifiers).
Foxo Guest is requiring a OTP validation if:
\n* The user provides an existing email address and some of the user identifiers are new and never been associated with a user account yet (`session_id`, user_id, ip_address)
* The email identifier provided via B2B API endpoint does not match the email the user provides while logging in
* If a user is already logged in with Foxo Guest but the user identifiers embedded into the outbound link do not match that user, the user will be forced to sign out and re-do the authentication flow
In either case, if the user logged in successfully the chat/case will be pre-populated with any additional details provided in the B2B API call (case subject, messages, etc).
\nAuthenticates the user account with the Foxo API, given correct API Key and Secret are provided. \nReturns a one-time access token in the response body's JSON, which can be used to access the other API operations. Note that for each operation a new access token has to be acquired.
\nResponds with 400/401 access codes and error messages if the payload is incorrect.
\n","urlObject":{"path":["api","v1"],"host":["{{FOXO_B2B_HOST}}"],"query":[],"variable":[]}},"response":[],"_postman_id":"108c8176-04fc-4384-9b09-af83f8111452"},{"name":"User Exists","id":"28d34b82-aff3-4288-8f21-265b1564a25f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"bearer","bearer":{"basicConfig":[{"key":"token","value":""}]},"isInherited":false},"method":"POST","header":[{"key":"Content-Type","value":"application/json","type":"text"},{"key":"X-Foxo-Action","value":"user-exists","type":"text"}],"body":{"mode":"raw","raw":"{\n \"email\": \"user@example.com\",\n \"ahpra_no\": \"MED1234567890\",\n \"mobile_phone\": \"0412345678\"\n}"},"url":"{{FOXO_B2B_HOST}}/api/v1","description":"Check if a user exists in the Foxo network. The email, ahpra_no or mobile_phone can be provided in the request body to check for user existence. \nWill return true or false in the data property of the JSON response based on if the user exists or not.
List users which have an integration setup with the API Users integration pattern. This means that if the API User is setup to handle integrations with ICON the endpoint's response will list users which have an ICON integration on setup with their user account. It won't list other users with other integration types.
The response will return an array of users in the data property of the JSON response and expose user_uid, email, last_name and first_name of that user. The user_uid can be used for all the request following which use their integration endpoints on their behalf.
Allows search for Foxo teams which are public in the Foxo platform. A searchText query parameter has to be provided with a text to search for.
\nThe response will return an array of teams in the data property of the JSON response and expose team_uid, name and description of that team (to be extended). The team_uid can be used to pass as parameters into other requests.
Initializes an (outbound) guest case chat on behalf of a user. A JSON object has to be provided in the request body:
\n{\n \"team_uid\": \"Required, the Foxo team_uid of the guest chat. The team_uid can be extracted from the guest chat link URL\",\n \"user_identifiers\": {\n // Information about the users identity associated with the integrators platform to uniquely identify them with Foxo Guest\n // At least one of the following has to be provided.\n \"session_id\": \"A session ID of the user logged in with the integrators platform\"\n \"user_id\": \"A user ID of the user logged in with the integrators platform\",\n \"email\": \"Email address of the user logged in with the integrators platform\",\n \"ip_address\": \"The IP address the user used in the integrators platform\"\n },\n \"subject\": \"Required subject of the newly created guest case\",\n \"messages\": [\n // Optional, an array of strings which will be created as first messages in the newly created guest chat\n ]\n}\n\nThe response will return a JSON object in the response body, containing an access_token which can be appended to a Foxo Guest chat URL via query string parameter ?guest_outbound_token=...
Example response:
\n{\n \"message\": \"Outbound guest token\",\n \"data\": {\n \"guest_outbound_token\": \"qkjl7pl3iltdbx\",\n \"guest_case_link\": \"{{FOXO_GUEST_HOST}}/chat/0d4c9142-989d-4ed1-b34e-eebb1e7c3597/new?guest_outbound_token=7y2l7pu52rxkcn\"\n }\n}\n\nSame endpoint https://github.com/foxo-tech/foxo-integration-api#create-patient, except the users endpoint is not called directly. Instead the API User has to first authenticate through the B2B API and then call this endpoint with a valid user_uid as part of the URL.
This is using the users integration endpoint on their behalf.
\nNOTE: In order tp use this endpoint with Postman the USER_UID has to be setup in Postman environment variables or can be copied directly into the URL of this request after the {{FOXO_B2B_HOST}}/api/v1/ part. E.g. {{FOXO_B2B_HOST}}/api/v1/032d931c-9228-490c-bf7b-37de4c005520. Note also that the USER_UID has to be a valid user_uid from a user listed in the response of the List integration users endpoint.
Same end https://github.com/foxo-tech/foxo-integration-api#list-available-teams, except the users endpoint is not called directly. Instead the API User has to first authenticate through the B2B API and then call this endpoint with a valid user_uid as part of the URL.
This is using the users integration endpoint on their behalf.
\nNOTE: In order tp use this endpoint with Postman the USER_UID has to be setup in Postman environment variables or can be copied directly into the URL of this request after the {{FOXO_B2B_HOST}}/api/v1/ part. E.g. {{FOXO_B2B_HOST}}/api/v1/032d931c-9228-490c-bf7b-37de4c005520. Note also that the USER_UID has to be a valid user_uid from a user listed in the response of the List integration users endpoint.
Same end https://github.com/foxo-tech/foxo-integration-api#create-patient, except the users endpoint is not called directly. Instead the API User has to first authenticate through the B2B API and then call this endpoint with a valid user_uid as part of the URL.
This is using the users integration endpoint on their behalf.
\nNOTE: In order tp use this endpoint with Postman the USER_UID has to be setup in Postman environment variables or can be copied directly into the URL of this request after the {{FOXO_B2B_HOST}}/api/v1/ part. E.g. {{FOXO_B2B_HOST}}/api/v1/032d931c-9228-490c-bf7b-37de4c005520. Note also that the USER_UID has to be a valid user_uid from a user listed in the response of the List integration users endpoint.
WARNING: This request will only work if the users integration is setup with teams within the Foxo app, so make sure this is the case.
\nWARNING: The Postman request is using a collection variable for the team_uid (team_uid1) to create a case for while the patient is created. The collection variable is set when executing the User Integration: Get Teams.
Same end https://github.com/foxo-tech/foxo-integration-api#create-patient, except the users endpoint is not called directly. Instead the API User has to first authenticate through the B2B API and then call this endpoint with a valid user_uid as part of the URL.
This is using the users integration endpoint on their behalf.
\nNOTE: In order tp use this endpoint with Postman the USER_UID has to be setup in Postman environment variables or can be copied directly into the URL of this request after the {{FOXO_B2B_HOST}}/api/v1/ part. E.g. {{FOXO_B2B_HOST}}/api/v1/032d931c-9228-490c-bf7b-37de4c005520. Note also that the USER_UID has to be a valid user_uid from a user listed in the response of the List integration users endpoint.
WARNING: This request will only work if the users integration is setup with teams within the Foxo app, so make sure this is the case.
\nWARNING: The Postman request is using a collection variable for the team_uid's (team_uid1 & team_uid2) to create a case for while the patient is created. The collection variables are set when executing the User Integration: Get Teams.
Same end https://github.com/foxo-tech/foxo-integration-api#create-patient, except the users endpoint is not called directly. Instead the API User has to first authenticate through the B2B API and then call this endpoint with a valid user_uid as part of the URL.
This is using the users integration endpoint on their behalf.
\nNOTE: In order tp use this endpoint with Postman the USER_UID has to be setup in Postman environment variables or can be copied directly into the URL of this request after the {{FOXO_B2B_HOST}}/api/v1/ part. E.g. {{FOXO_B2B_HOST}}/api/v1/032d931c-9228-490c-bf7b-37de4c005520. Note also that the USER_UID has to be a valid user_uid from a user listed in the response of the List integration users endpoint.
WARNING: This request will only work if the users integration is setup with teams within the Foxo app, so make sure this is the case.
\nWARNING: The Postman request is using a collection variable for the team_uid (team_uid1) to create a case for while the patient is created. The collection variable is set when executing the User Integration: Get Teams.
Same end https://github.com/foxo-tech/foxo-integration-api#upload-and-attach-media, except the users endpoint is not called directly. Instead the API User has to first authenticate through the B2B API and then call this endpoint with a valid user_uid as part of the URL.
This is using the users integration endpoint on their behalf.
\nNOTE: In order tp use this endpoint with Postman the USER_UID has to be setup in Postman environment variables or can be copied directly into the URL of this request {{FOXO_B2B_HOST}}/api/v1/ part. E.g. {{FOXO_B2B_HOST}}/api/v1/032d931c-9228-490c-bf7b-37de4c005520. Note also that the USER_UID has to be a valid user_uid from a user listed in the response of the List integration users endpoint.
WARNING: The Postman request is using a collection variable for the patient_uid (patientWithCaseSubjectAndMessage) to attach the media to the patient. The collection variable is set when executing the User Integration: Add Patient + Send Case (with subject and message).
Same end https://github.com/foxo-tech/foxo-integration-api#upload-and-attach-media, except the users endpoint is not called directly. Instead the API User has to first authenticate through the B2B API and then call this endpoint with a valid user_uid as part of the URL.
This is using the users integration endpoint on their behalf.
\nNOTE: In order to use this endpoint with Postman the USER_UID has to be setup in Postman environment variables or can be copied directly into the URL of this request after the {{FOXO_B2B_HOST}}/api/v1/ part. E.g. {{FOXO_B2B_HOST}}/api/v1/032d931c-9228-490c-bf7b-37de4c005520. Note also that the USER_UID has to be a valid user_uid from a user listed in the response of the List integration users endpoint.
WARNING: The Postman request is using a collection variable for the case_key (caseKey) to attach the media to the case. The collection variable is set when executing the User Integration: Add Patient + Send Case (with subject and message).