Skip to main content

Survey

Managing surveys in the Bingli API allows for creating, fetching, and retrieving survey-related data, including responses, diagnoses, and summaries.

API Environments​

Bingli provides multiple environments for different use cases:

  • Production EU: https://fhir-gateway.api.bingli.eu/tenant-api/survey/
  • Acceptance EU: https://fhir-gateway.api.acc.bingli.be/tenant-api/survey/
  • Production US: https://fhir-gateway.api.bingli.us/tenant-api/survey/

Creating a Survey​

POST - Create Survey​

Endpoint​

https://fhir-gateway.api.acc.bingli.be/tenant-api/survey

Description​

This endpoint creates a new survey task for a given patient. You can either provide a patientId or pass a complete patient object.

Request Details​

Headers​

KeyValue
Content-Typeapplication/json
AuthorizationBearer JWTTOKEN

Body (Raw JSON)​

{
  "patientId": "b204a42f-9fd2-4585-a4ff-13a4f3a3c1fd",
  "includeUrl": true,
  "includePinInUrl": true
}

Alternative Payload with Full Patient Object​

{
  "patient": {
    "firstName": "Francis",
    "lastName": "Rousseau",
    "gender": "male",
    "birthdate": "2025-02-11T11:54:31.874Z",
    "language": "nl-be",
    "email": "frr@mybingli.com",
    "phone": {
      "phoneNumber": "+32471810697",
      "type": "mobile",
      "countryIsoAlpha2": "BE"
    },
    "externalReference": "EXTERNAL-REF-123"
  },
  "includeUrl": true,
  "includePinInUrl": true,
  "sendInvitation": true,
  "communicationServiceTypes": "sms"
}

cURL Request​

curl --location 'https://fhir-gateway.api.acc.bingli.be/tenant-api/survey' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <TOKEN>' \
--data '{
  "patientId": "b204a42f-9fd2-4585-a4ff-13a4f3a3c1fd",
  "includeUrl": true,
  "includePinInUrl": true
}'

Parameters Explanation​

  • patient.firstName: Patient's first name(s).
  • patient.lastName: Patient's last name.
  • patient.gender: Patient's gender (male or female).
  • patient.birthDate: Patient's date of birth (YYYY-MM-DD).
  • patient.language: The preferred language of the patient.
  • patient.email: Patient's email.
  • patient.phone.phoneNumber: Patient's phone number.
  • patient.phone.type: Patient's phone type. Can be mobile, landline, or cordless.
  • patient.phone.countryIsoAlpha2: Patient's phone two-letter country code.
  • patient.externalReference: Unique identifier for the patient in your system.
  • patientId: patientId given by the Create Patient endpoint.
  • includeUrl: Include survey URL (true/false).
  • includePinInUrl: Include the pin in the URL for disabling 2FA (true/false).
  • sendInvitation: Choose to send an invitation yes or no (true/false).
  • communicationServiceTypes: Select invitation possibility (email/sms).

Fetching a Survey with Answers​

GET - Fetch Survey​

Endpoint​

https://fhir-gateway.api.acc.bingli.be/tenant-api/survey/{SURVEY-ID}

Description​

This endpoint returns all answers recorded for a given survey, identified by the surveyId.

cURL Request​

curl --location --request GET 'https://fhir-gateway.api.acc.bingli.be/tenant-api/survey/{SURVEY-ID}' \
--header 'Authorization: Bearer <TOKEN>'

Example Response​

{
    "answers": [
        {
            "questionCode": "Do you work at Sanday?",
            "questionLabel": "Do you work at Sanday?",
            "answerValues": ["Yes"]
        }
    ],
    "confirmedDiagnoses": {
        "diagnoses": []
    },
    "alerts": [],
    "surveyId": "930ec50f-85df-49ae-81c4-3555fde43bd7",
    "status": "inProgress",
    "createdAt": "2025-02-11T11:52:05.496214Z"
}

Parameters Explanation​

  • surveyId: surveyId given by the Create Survey endpoint.

Fetching a Survey History​

GET - Fetch Surveys for Patient​

Endpoint​

https://fhir-gateway.api.acc.bingli.be/tenant-api/survey/history/{SURVEY-ID}

Description​

This endpoint returns this history associated with a given survey, identified by the unique surveyId.

cURL Request​

curl --location 'https://fhir-gateway.api.acc.bingli.be/tenant-api/survey/history/{SURVEY-ID}' \
--header 'Authorization: Bearer <TOKEN>'

Example Response​

[
    {
        "surveyChangeLogId": "88d12345-cd88-7fyt-aa88-8899b492de43",
        "surveyId": "930ec50f-85df-49ae-81c4-3555fde43bd7",
        "timestamp": "2025-03-27T16:35:40.655469Z",
        "type": "workflow",
        "userId": "09645c04-ef4f-4004-ad81-1e0593850619",
        "userFirstName": "System",
        "userLastName": "User",
        "userEmail": "Wizard",
        "content": {
            "$type": "workflow",
            "workflowStepId": "3ad0118e-72ad-4a49-7788-b459dc2576c1"
        }
    },
    {
        "surveyChangeLogId": "9777ef39-2349-49fc-bc6c-f66eb544567d",
        "surveyId": "930ec50f-85df-49ae-81c4-3555fde43bd7",
        "timestamp": "2025-03-27T16:37:25.986311Z",
        "type": "claim",
        "userId": "6dfkl9ce-1b2c-4993-c99x-910aeb12489a",
        "userFirstName": "Francis",
        "userLastName": "Rousseau",
        "userEmail": "frr@mybingli.com",
        "content": {
            "$type": "claim",
            "isClaimed": true
        }
    }
]

Parameters Explanation​

  • surveyId: surveyId given by the Create Survey endpoint.

Fetching All Surveys for a Patient​

GET - Fetch Surveys for Patient​

Endpoint​

https://fhir-gateway.api.acc.bingli.be/tenant-api/survey/patient/{PATIENT-ID}

Description​

This endpoint returns all surveys associated with a given patient, identified by the unique patientId.

cURL Request​

curl --location 'https://fhir-gateway.api.acc.bingli.be/tenant-api/survey/patient/{PATIENT-ID}' \
--header 'Authorization: Bearer <TOKEN>'

Parameters Explanation​

  • patientId: patientId given by the Create Patient endpoint.

Fetching Survey Summaries​

GET - Fetch Plain Text Summary​

Endpoint​

https://fhir-gateway.api.acc.bingli.be/tenant-api/survey/{SURVEY-ID}/summary/plain-text

Description​

This endpoint returns the summary details for a given survey, identified by the surveyId, in plain text.

cURL Request​

curl --location --request GET 'https://fhir-gateway.api.acc.bingli.be/tenant-api/survey/{SURVEY-ID}/summary/plain-text' \
--header 'Authorization: Bearer <TOKEN>'

Example Response​

{
    "value": "Additional comments or info\n  Do you work at Sanday?: Yes\n  Give your rating of Sanday!: Very good!\n\n"
}

Parameters Explanation​

  • surveyId: surveyId given by the Create Survey endpoint.

GET - Fetch PDF Summary​

Endpoint​

https://fhir-gateway.api.acc.bingli.be/tenant-api/survey/{SURVEY-ID}/summary/pdf

Description​

This endpoint returns a Base64-encoded PDF of the survey summary for a given survey, identified by the surveyId.

cURL Request​

curl --location --request GET 'https://fhir-gateway.api.acc.bingli.be/tenant-api/survey/{SURVEY-ID}/summary/pdf' \
--header 'Authorization: Bearer <TOKEN>'

Parameters Explanation​

  • surveyId: surveyId given by the Create Survey endpoint.

Response​

This request returns a Base64-encoded PDF of the survey summary.

Conclusion​

Managing surveys through the Bingli API allows efficient creation, retrieval, and fetching of responses. The ability to pass a complete patient object simplifies the process of associating surveys with patient records. For further details, refer to the Bingli API Documentation or contact support@mybingli.com.