# Overview ## Welcome to mio.ID Business This documentation provides step-by-step guidance on integrating mio.ID services into your application. ## Why mio.ID? mio.ID empowers businesses to accelerate digital transformation and enhance scalability by optimizing client onboarding and risk management processes. By incorporating advanced identity verification and background checks, our platform helps reduce risks while ensuring regulatory compliance. ## Key Benefits of mio.ID Integration * **Faster Approvals:** Streamline the onboarding process with pre-approved identity trust, enabling quicker client activation and preferred rates. * **Enhanced Revenue and Conversion:** Improve conversion rates with seamless, frictionless experiences that attract and retain clients. * **Advanced Biometric Solutions:** Simplify payments and authentication through cutting-edge biometric verification, offering a secure and efficient alternative to traditional methods. * **Risk Management and Compliance:** Effectively mitigate risks and maintain compliance with regulatory requirements through robust identity and transaction monitoring tools. * **Operational Efficiency:** Automate workflows to reduce manual errors and increase productivity, ensuring a smooth client journey from onboarding to ongoing interactions. By integrating mio.ID, businesses can deliver a secure, seamless client experience, positioning themselves as trusted providers in an increasingly competitive digital landscape.\ Let’s get started — explore how mio.ID can transform your operations today! # Data Dictionary The Data Dictionary serves as a comprehensive guide to understanding and utilizing the various data objects available through our API. It provides detailed descriptions, field definitions, and relationships for key entities like Objects and Taxonomy, enabling developers to fully integrate and optimize their use of the mio.ID platform. This section is an essential reference for structuring API calls and interpreting responses, ensuring accurate and efficient interaction with our system. By exploring the pages linked here, you'll gain insights into how to utilize the platform's features, such as Activities, Members, and Requirements, and adapt them to your specific needs. # Glossary The Glossary provides a comprehensive reference for key terms and concepts used throughout the mio.ID developer documentation. This section is divided into subsections, each focusing on a specific aspect of the platform, offering clear and concise definitions to aid understanding and implementation. ### Subsections #### [Entity or Member](/api-reference/data-dictionary/glossary/entity-or-member) This subsection explains the structure and attributes of entities and members in the mio.ID platform. It outlines how individuals and businesses are represented within the system, their unique identifiers, and associated metadata. #### [Activity](/api-reference/data-dictionary/glossary/activity) This subsection defines activities within the mio.ID ecosystem. It describes the various actions and events tracked on the platform, including their structure, types, statuses, and related metadata. #### [Requirement](/api-reference/data-dictionary/glossary/requirement) This subsection elaborates on the requirements object. It details how specific personal details or documents are requested, shared, or processed between entities during an activity. The Glossary serves as a central resource for understanding the terminology and parameters critical for integrating and leveraging mio.ID’s API capabilities. # Entity or Member The *Entity or Member* object within the mio.ID platform represents individuals or businesses registered within the system. This object contains metadata such as unique identifiers, avatar/logo, identity trust score, and other details crucial for recognizing and interacting with the registered participants in the platform. Both individuals and businesses can be categorized as members, and each member is assigned a unique identifier to distinguish them within the system. ## Member Type Defines the type of user registered in mio.ID.
TypeDescription
INDIVIDUALRepresents a single user or consumer.
BUSINESSRepresents a company or organization..
## Identity Trust Score Level This determines the identity trust level based entirely on the user's scoring at the moment.
LevelDescription
POORTrust score range: 300 - 499
FAIRInTrust score range: 500 - 649
GOODTrust score range: 650 - 749
EXCELENTTrust score range: 750 - 850
## Identity Trust Score This is the numerical value representing the level of trust associated with the user's identity, calculated based on various factors.
ScoreDescription
300 - 850The trust score is calculated within a range of 300 to 850. The higher the score, the more trustworthy the user’s identity is considered.
This score helps assess the risk and reliability of the user or business within the platform, facilitating safer transactions and interactions. # Activity The *Activity* section defines the different types of interactions and statuses available within the mio.ID platform. It helps users understand the nature of actions, their outcomes, and how they evolve over time. ## Activity Type Each activity type represents a distinct interaction initiated or received within the platform:
TypeDescription
AT_001Request Details: An initiator sends a request to a receptor, asking for approval to access their personal details.
AT_002Share Details: An initiator shares their personal details directly with the receptor without requiring further approval.
AT_003Swap Details: A reciprocal exchange of personal details. The receptor can accept all or part of the requested details, which become visible to both parties.
AT_004Authorization Request: A request for transaction or process approval. This may include BioFace authentication for enhanced security and verification.
## Activity Status Statuses track the current state of an activity, helping users understand its progression and outcome:
StatusDescription
SENT

The activity has been created and is pending the receptor’s attention.

This status is visible only to the initiator.

ACTION_REQUIRED

The activity is awaiting the receptor's response within the specified validity period.

This status is visible only to the receptor.

ACCEPTEDThe receptor has approved the activity. Accepted personal details are shared and visible to both parties for the duration of the defined sharing period.
DECLINEDThe receptor has declined the activity. No personal details will be shared or visible to either party.
CANCELEDThe activity was not attended to within the validity period and is now inactive. No personal details were shared or made visible.
EXPIREDThe sharing period defined by the receptor has ended, and the activity is no longer valid. No personal details are accessible to either party.
COMPLETEDBoth parties have finalized the activity successfully. Any shared personal details remain visible within the agreed sharing period.
# Requirement The Requirement object defines the personal details, actions, or validations requested by the initiator of an activity. It ensures flexibility by allowing the recipient (receptor) to decide which details to share while meeting the requirements of the activity. ## Requirement Type The Requirement Type specifies the format or nature of the requested data or action in an activity. **Available in: GET** (response only).
TypeDescription
RTP_001Requires the execution of a BioFace Authentication Flow.
RTP_002Requests personal details in the form of structured data values (JSON object).
RTP_003Requests images, such as selfies or identity document photos (front and back) as a binary file.
RTP_004Requests a combination of structured personal details (RTP_002) OR image data (RTP_003).
RTP_005Requests a combination of structured personal details (RTP_002) AND image data (RTP_003).
## Requirement Category The Requirement Category groups requirements into logical categories based on the type of information being requested. **Available in: GET** (response only).
CategoryDescription
RQC_001Refers to Identity-related personal details.
RQC_002Refers to Background-related personal details.
RQC_003Refers to Document-related details
## Requirement Code The Requirement Code uniquely identifies a group of personal detail requirements, requests, or actions within an activity. Each Requirement Item specifies the precise data or action associated with the requirement, outlining what will be included in the request. The table below lists all available Requirement Codes and their corresponding Requirement Items, which can be included in a request. **Available in: POST** (request) and **GET** (response).
CodeDescriptionRequirement Items
RQ_001BioFace Authentication-
RQ_002Identity Trust
  • IDT_001 Member Since
  • IDT_002 Identity Trust Score
  • IDT_003 Identity Trust Score Level
  • IDT_004 IDV Timestamp
RQ_003Selfie-
RQ_004Personal Information
  • PIF_001 Profile Name
  • PIF_002 Fullname
  • PIF_003 Surname
  • PIF_004 Given names
  • PIF_005 Date of Birth
  • PIF_006 Gender
  • PIF_007 Marital Status
RQ_005Nationality-
RQ_006Identity Document
  • IDC_001 Frontside image
  • IDC_002 Backside image
  • IDC_003 Document Information
RQ_007Address-
RQ_008Phone-
RQ_009Email-
RQ_010Government Tax ID-
RQ_011Occupation-
RQ_012Employment-
RQ_013Compliance-
RQ_014Income-
RQ_015Proof of Residence-
RQ_016Proof of Income-
RQ_017Proof of Employment-
RQ_018Proof of Education-
RQ_019Proof of Ownership-
RQ_020Proof of Funds-
RQ_021Proof of Insurance-
RQ_022Legal Document-
RQ_023House Owner-
RQ_024Housing Monthly Cost-
## Accepted Requirements The Accepted Requirement items uniquely identify the details of the elements associated with the Requirement Items. These accepted elements are grouped under a Requirement Code and represent the data included in the response. The table below lists all available Acceptance Codes returned as part of the response.
RequirementPropertyExample
RQ_002items
[
  {
    "code": "IDT_001", // Member Since
    "data": {
      "value": 1704085200000
    }
  },
  {
    "code": "IDT_002", // Identity Trust Score
    "data": {
      "value": 450
    }
  },
  {
    "code": "IDT_003", // Identity Trust Score Level
    "data": {
      "value": "POOR"
    }
  },
  {
    "code": "IDT_004", // IDV Timestamp
    "data": {
      "datetime": 1704085200000
    }
  }
]
RQ_003data
{
  "url": "https://url.com/my-selfie.png"
}
RQ_004items
[
  {
    "code": "PIF_001", // Profile Name
    "data": {
      "value": "John Doe"
    }
  },
  {
    "code": "PIF_002", // Fullname
    "data": {
      "value": "John Martin Doe"
    }
  },
  {
    "code": "PIF_003", // Surname
    "data": {
      "value": "Doe"
    }
  },
  {
    "code": "PIF_004", // Given names
    "data": {
      "value": "John Martin"
    }
  },
  {
    "code": "PIF_005", // Date of Birth
    "data": {
      "value": "1984-12-31"
    }
  },
  {
    "code": "PIF_006", // Gender
    "data": {
      "value": "M"
    }
  },
  {
    "code": "PIF_007", // Marital Status
    "data": {
      "value": "Single"
    }
  }
]
RQ_005data
{
  "nationality": "US"
}
RQ_006items
[
  {
    "code": "IDC_001", // Frontside image
    "data": {
      "url": "https://url.com/front-image.png"
    }
  },
  {
    "code": "IDC_002", // Backside image
    "data": {
      "url": "https://url.com/back-image.png"
    }
  },
  {
    "code": "IDC_003", // Document Information
    "data": {
      "fullname": "John Martin Doe",
      "given_names": "John Martin",
      "surnames": "Doe",
      "first_name": "John",
      "middle_name": "Martin",
      "surname": "Doe",
      "second_surname": null,
      "gender": "M",
      "age": "40",
      "date_of_birth": "1984-12-31",
      "marital_status": "Single",
      "height": "5'10''",
      "weight": "220lb",
      "eyes_color": "Blue",
      "hair_color": "Black",
      "nationality": "US",
      "place_of_birth": "US",
      "address": "1853 E Orleans St.",
      "city": "Philadelphia",
      "state": "Pennsylvania",
      "zipcode": "19134",
      "address_country": "US",
      "category": "Government issued-id",
      "type": "PASSPORT",
      "type_name": "Passport",
      "id_number": "987654321",
      "alternate_number": "12345678",
      "document_place_of_issue": "US",
      "document_issuing_state": "PA",
      "document_issuing_state_name": "Pennsylvania",
      "document_issuing_country": "US",
      "document_issuing_date": "2020-01-01",
      "document_expiration_date": "2029-12-31",
      "rfid_present": true
    }
  }
]
RQ_007data
{
  "country": "US",
  "state": "Pennsylvania",
  "city": "Philadelphia",
  "address": "1853 E Orleans St.",
  "zipcode": "19134"
}
RQ_008data
{
  "country_code": "US",
  "number": "9876543210"
}
RQ_009data
{
  "recipient": "playground@preventor.com"
}
RQ_010data
{
  "country": "PE",
  "type": "BT_001",
  "number": "456BH9312B1"
}
RQ_011data
{
  "code": "OCC_004"
}
RQ_012data
{
  "status": "EMS_001",
  "title": "Engineer",
  "start_date": "2024-01-01",
  "end_date": "2028-12-31",
  "employer": {
    "name": "Microsoft Corp.",
    "address": {
      "country": "US",
      "city": "Philadelphia",
      "state": "Pennsylvania",
      "address": "1801 E Orleans St.",
      "zipcode": "19134"
    }
  }
}
RQ_014data
{
  "currency": "USD",
  "income": 300000,
  "symbol": "$"
}
RQ_015data
{
  "type": "DCT_001",
  "name": "Document of residence",
  "owner": "Donald Trump",
  "issuing_entity": "US Government",
  "issuing_date": "2020-01-01",
  "expiration_date": "2030-05-30",
  "url": "https://url.com/document"
}
RQ_016data
{
  "type": "DCT_002",
  "name": "Payment bill",
  "owner": "Donald Trump",
  "issuing_entity": "Microsoft Corp.",
  "issuing_date": "2020-01-01",
  "url": "https://url.com/document"
}
RQ_017data
{
  "type": "DCT_003",
  "name": "Employment contract",
  "owner": "Donald Trump",
  "issuing_entity": "Google LLC",
  "issuing_date": "2020-01-01",
  "expiration_date": "2030-05-30",
  "url": "https://url.com/document"
}
RQ_018data
{
  "type": "DCT_004",
  "name": "Graduation document",
  "owner": "Donald Trump",
  "issuing_entity": "Georgia University",
  "issuing_date": "1985-01-01",
  "url": "https://url.com/document"
}
RQ_019data
{
  "type": "DCT_005",
  "name": "House ownership",
  "owner": "Donald Trump",
  "issuing_entity": "US Government",
  "issuing_date": "2020-01-01",
  "url": "https://url.com/document"
}
RQ_020data
{
  "type": "DCT_006",
  "name": "Funds inform",
  "owner": "Donald Trump",
  "issuing_entity": "US Government",
  "issuing_date": "2020-01-01",
  "url": "https://url.com/document"
}
RQ_021data
{
  "type": "DCT_007",
  "name": "Insurance contract",
  "owner": "Donald Trump",
  "issuing_entity": "US Government",
  "issuing_date": "2020-01-01",
  "expiration_date": "2030-05-30",
  "url": "https://url.com/document"
}
RQ_022data
{
  "type": "DCT_008",
  "name": "Divorce agreement",
  "owner": "Donald Trump",
  "issuing_entity": "US Government",
  "issuing_date": "2020-01-01",
  "url": "https://url.com/document"
}
RQ_023data
{
  "is_owner": false
}
RQ_024data
{
  "currency": "USD",
  "symbol": "$",
  "cost": 80000
}
# Objects Across our API endpoints, several key objects are available to interact with, each serving a specific function within the mio.ID ecosystem. Below is a summary of the core objects and links to their detailed descriptions, including fields and use cases: * [Member](/api-reference/data-dictionary/objects/entity-or-member)\ Represents a registered individual or business in the mio.ID platform.\ **Use Case:** Interact with individuals or businesses, verify identity, or initiate activities.\ **Endpoints:** Accessible through Community-related APIs. * [Activity](/api-reference/data-dictionary/objects/activity)\ Represents requests, sharings, or exchanges initiated by members or businesses.\ **Use Case:** Create, track, or respond to data-sharing requests between entities.\ **Endpoints:** Includes APIs to list activities, retrieve details, and create requests. * [Requirement](/api-reference/data-dictionary/objects/requirement)\ Defines conditions or prerequisites associated with an activity.\ **Use Case:** Set or retrieve specific requirements necessary to complete an interaction.\ **Endpoints:** Useful for customizing workflows based on compliance or business logic. * [Webhook](/api-reference/data-dictionary/objects/webhook)\ Represents a configured endpoint for receiving real-time event notifications. **Use Case:** Automate workflows by subscribing to events like activity updates or member changes.\ **Endpoints:** Manage webhooks to receive notifications for specified events. For detailed field information, request structure, and usage examples, refer to the respective object documentation in the [API](/api-reference/api-endpoints) Developer Guide. # Entity or Member The **Entity** or **Member** profile object represents the metadata associated with a mio.ID account, encapsulating essential information about the individual or business entity tied to the profile. ### Primary Use This object is the main data structure returned by the **Community Endpoint**, providing comprehensive details about registered users or businesses. ### Contextual Use The **Member** object can also appear as a nested child within the **Activity Object**, where it provides specific details related to user interactions, such as transaction approvals, data sharing, or other events within the mio.ID ecosystem. ### Representation The **Entity or Member** object supports both: * **Individuals (users)**: Personal accounts tied to a single user. * **Businesses**: Profiles associated with registered organizations. This flexibility ensures robust data handling for diverse use cases across the mio.ID platform. ### Fields
FieldTypeDescription
idstringThe unique identifier for a mioID entity or member.
namestringName of this member.
cifcodestringA secondary unique identifier, often referred to as the business's customer unique ID.
typestringSpecifies the type of registered member.
It can be either INDIVIDUAL or BUSINESS
Rfer to Member Type for more information.
avatarstringThe URL of the avatar or logo associated with a business member.
scorenumberThe identity trust score of the member.
scoring_levelstring

The trust score level of the member's identity.
It can be:

  • POOR
  • FAIR
  • GOOD
  • EXCELLENT

Refer to Identity Trust Score Level for more information.

social_mediaarrayA collection of objects containing metadata about the business member's social media profiles.
created_atnumberThe timestamp representing when the member registered on the mioID platform (also known as the "member since" date).
unregisteredbooleanIndicates whether the member has deleted their profile from the mioID platform.
Note: This property is only included in the Activity child object for historical purposes.
# Activity The **Activity** object represents the various types of actions and events within the mio.ID platform, initiated by or involving both individual and business entities. It is a key component for tracking, analyzing, and reporting interactions, providing detailed metadata about each activity's lifecycle and status. ### Fields
FieldTypeDescription
idstringUnique identifier for this activity
entityobjectThe participant involved in the activity, either sending or receiving it.
Refer to Member for more information.
typestring

Specifies the type of activity.
Its values can be:

  • AT_001
  • AT_002
  • AT_003
  • AT_004

Refer to Activity Type for more information.

type_namestringHuman-readable description of the activity type.
in_out_boundstring

Indicates the direction of the activity.
Its value can be:

  • IN (Inbound)
  • OUT (Outbound)
requirementsarrayList of Requirements requested or shared during the activity.
accepted_requirementsarrayList of Requirements that the recipient accepted to share with the initiator.
declined_requirementsarrayList of Requirements that the recipient declined to share.
descriptionstringA message from the initiator sent as part of the activity.
statusstringCurrent status of the activity.
Refer to Activity Status for more information.
notification_messagestringA completion message sent by the recipient to the initiator when the activity is completed.
timelinearrayA log of activity statuses and their timestamps.
time_zonestringThe timezone in which the activity occurred.
expires_inobjectPeriod for which the activity is valid, set by the recipient. Once expired, the initiator loses access to the recipient's shared details.
expires_atnumberTimestamp indicating when the personal details are no longer available to the initiator due to expiration.
attended_atnumberTimestamp when the recipient made a decision (accepted or declined).
completed_atnumberTimestamp when the activity was marked as COMPLETED.
valid_untilnumberTime limit for the recipient to decide on the activity. Once expired, the activity becomes inactive.
created_atobjectDatetime when Activity has been created.
updated_atobjectDatetime when Activity has been updated.
# Requirement The **Requirements** object represents personal details requested by the initiator during an activity. The recipient (receptor) determines which details to share to complete the activity. ### Fields
FieldTypeDescription
codestringUnique identifier for this requirement.
typestringSpecifies the type of requirement.
categorystringCategory of the requirement.
dataobjectContains personal details for requirements involving data sharing.
Note: This field appears only in the accepted_requirements array within the Activity object.
itemsarray

Contains a detailed list of personal details involving grouped requirements. Examples include:

  • IDENTITY TRUST = "RQ_002"
  • PERSONAL INFO = "RQ_004"
  • IDENTITY DOCUMENT = "RQ_006"

Note: Refer to the Requirement Item table for structure details.

## Requirement Item The **Requirement Item** object represents detailed sub-requirements within a larger group of personal details requested during an activity.
FieldTypeDescription
codestringUnique code identifying this specific inner requirement
typestringSpecifies the type of sub-requirement.
dataobject

Contains a detailed list of personal details associated with grouped requirements.
Examples include:

  • IDENTITY TRUST = "RQ_002"
  • PERSONAL INFO = "RQ_004"
  • IDENTITY DOCUMENT = "RQ_006"

Note: This field appears only in the accepted_requirements array within the Activity object.

This structure allows for a more granular breakdown of individual requirements, ensuring clarity and flexibility during implementation. # Webhook The **Webhook** object facilitates the integration of your application with the mio.ID platform by enabling real-time event notifications. This object defines a configured endpoint in your system that receives notifications about actions or changes in mio.ID services, ensuring seamless automation and synchronization.
FieldTypeDescription
typestringSpecifies the type of webhook.
urlstringThe URL of your service to be used as the webhook endpoint.
secretstringA secret key used to cipher messages for secure communication.
Note: Refer to Webhooks Configuration for details about the ciphering process.
authorizationobject

Provides options for securing your service using one of the following methods:

  • Basic authentication
  • Bearer token authorization
  • API key
headersobjectAllows configuration of additional metadata to be included in the headers for your service. This ensures compatibility with services requiring custom metadata.
This structure supports robust, secure integration for handling real-time updates and actions on the mio.ID platform. # API endpoints The API Endpoints section provides a detailed guide to interacting with the mio.ID platform. It outlines the key services and functionalities available through our API, including Authentication, Community, Activities, and Webhooks. Each endpoint is described with its purpose, supported methods, and integration details, helping you build secure and efficient workflows. This section is your roadmap for leveraging mio.ID's capabilities, from authenticating users to managing data exchanges and receiving event-driven notifications. Dive into each subsection to explore how to implement these features seamlessly into your applications. Please, refer to our [API documentation](https://api.mio.id/business/docs/#/) to see more information about our endpoints. # Authentication To access our services, you need to be both authenticated and authorized. The first step is to generate an access token. This token is essential for secure interaction with our API and ensures that only authorized users can access the services. ### Credentials for Token Generation To create your access token, you will need the following credentials, which were provided to you via email: * **Key:** A unique identifier for your application. * **Username:** Your assigned username. * **Password:** The corresponding password for your username. ### How to Authenticate **Send Your Key as a Header:** Include your key in the request header under the field Authorization-Key. **Use Basic Authorization for Username and Password:** Combine your username and password into a Basic Authorization header. This involves encoding the username:password pair using Base64. POST [Create JWT token](#business-v1-auth) {% openapi src="/files/4oCk75nmswflQbV3VZRH" path="/business/v1/auth" method="post" %} [swagger-business.json](https://2093545926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3zb7cV9cfl5Gboof9fgA%2Fuploads%2FHWyPy65zoM8khgjBWXf6%2Fswagger-business.json?alt=media\&token=e0976cfc-eb2b-41b2-886b-7bcea292c232) {% endopenapi %} # Community The Community endpoint provides access to all registered users on the mio.ID platform, including individuals and businesses. This allows your application to interact with users by sending or receiving activities such as identity verification requests, compliance checks, or other transactions. GET [List All Members](#business-v1-community)\ Retrieves a comprehensive list of registered users. GET [Search Member by Phone number](#business-v1-community-phone-phone)\ Locates a specific individual or business by their associated phone number.
{% openapi src="/files/4oCk75nmswflQbV3VZRH" path="/business/v1/community" method="get" %} [swagger-business.json](https://2093545926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3zb7cV9cfl5Gboof9fgA%2Fuploads%2FHWyPy65zoM8khgjBWXf6%2Fswagger-business.json?alt=media\&token=e0976cfc-eb2b-41b2-886b-7bcea292c232) {% endopenapi %} {% openapi src="/files/4oCk75nmswflQbV3VZRH" path="/business/v1/community/phone/{phone}" method="get" %} [swagger-business.json](https://2093545926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3zb7cV9cfl5Gboof9fgA%2Fuploads%2FHWyPy65zoM8khgjBWXf6%2Fswagger-business.json?alt=media\&token=e0976cfc-eb2b-41b2-886b-7bcea292c232) {% endopenapi %} # Activities The Activities endpoints represents the core interactions within the mio.ID platform. These interactions, such as requests, sharings, or exchanges, enable members from the mio.ID Community to securely share their data with one another. GET [List of activities](#business-v1-activities)\ Fetches a list of all activities related to your business account, including both sent and received interactions. GET [Activity details](#business-v1-activities-activity)\ Retrieves detailed information about a specific activity using its unique identifier. {% openapi src="/files/4oCk75nmswflQbV3VZRH" path="/business/v1/activities" method="get" %} [swagger-business.json](https://2093545926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3zb7cV9cfl5Gboof9fgA%2Fuploads%2FHWyPy65zoM8khgjBWXf6%2Fswagger-business.json?alt=media\&token=e0976cfc-eb2b-41b2-886b-7bcea292c232) {% endopenapi %} {% openapi src="/files/4oCk75nmswflQbV3VZRH" path="/business/v1/activities/{activity}" method="get" %} [swagger-business.json](https://2093545926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3zb7cV9cfl5Gboof9fgA%2Fuploads%2FHWyPy65zoM8khgjBWXf6%2Fswagger-business.json?alt=media\&token=e0976cfc-eb2b-41b2-886b-7bcea292c232) {% endopenapi %} # Requests {% openapi src="/files/4oCk75nmswflQbV3VZRH" path="/business/v1/activities/requests" method="post" %} [swagger-business.json](https://2093545926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3zb7cV9cfl5Gboof9fgA%2Fuploads%2FHWyPy65zoM8khgjBWXf6%2Fswagger-business.json?alt=media\&token=e0976cfc-eb2b-41b2-886b-7bcea292c232) {% endopenapi %} # Authorizations {% openapi src="/files/4oCk75nmswflQbV3VZRH" path="/business/v1/activities/authorizations" method="post" %} [swagger-business.json](https://2093545926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3zb7cV9cfl5Gboof9fgA%2Fuploads%2FHWyPy65zoM8khgjBWXf6%2Fswagger-business.json?alt=media\&token=e0976cfc-eb2b-41b2-886b-7bcea292c232) {% endopenapi %} # Webhooks The Webhooks feature allows you to configure endpoints on your server to receive real-time event notifications from our system. By setting up a webhook, you can automate workflows, track updates, or respond to specific events programmatically. GET [List of webhooks](#business-v1-settings-webhooks) PUT [Create/Update webhook](#business-v1-settings-webhooks-1) DELETE [Delete your webhook](#business-v1-settings-webhooks-id) {% openapi src="/files/4oCk75nmswflQbV3VZRH" path="/business/v1/settings/webhooks" method="get" %} [swagger-business.json](https://2093545926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3zb7cV9cfl5Gboof9fgA%2Fuploads%2FHWyPy65zoM8khgjBWXf6%2Fswagger-business.json?alt=media\&token=e0976cfc-eb2b-41b2-886b-7bcea292c232) {% endopenapi %} {% openapi src="/files/4oCk75nmswflQbV3VZRH" path="/business/v1/settings/webhooks" method="put" %} [swagger-business.json](https://2093545926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3zb7cV9cfl5Gboof9fgA%2Fuploads%2FHWyPy65zoM8khgjBWXf6%2Fswagger-business.json?alt=media\&token=e0976cfc-eb2b-41b2-886b-7bcea292c232) {% endopenapi %} {% openapi src="/files/4oCk75nmswflQbV3VZRH" path="/business/v1/settings/webhooks/{id}" method="delete" %} [swagger-business.json](https://2093545926-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F3zb7cV9cfl5Gboof9fgA%2Fuploads%2FHWyPy65zoM8khgjBWXf6%2Fswagger-business.json?alt=media\&token=e0976cfc-eb2b-41b2-886b-7bcea292c232) {% endopenapi %} # Registration ### Registering your Webhook Service To properly set up and receive incoming webhooks, your server must expose an endpoint capable of handling the following: Webhooks are delivered as POST requests. The payload format depends on the configuration. **Encrypted Payload:** If a secret key is set, the payload will be delivered in raw text/plain.\ **Unencrypted Payload:** If no secret key is configured, the payload will be in standard application/json format. ### Testing Webhooks Before deploying, you can test your webhook configuration using tools like . These services allow you to capture and inspect the incoming requests to ensure your server is correctly processing them. ### Steps to Register you Webhook Configure your endpoint:\ \- Listen for POST requests.\ \- Handle both text/plain and application/json payloads.\ \- Verify and authenticate requests if using a secret. Test your endpoint: Use your developer dashboard to send test events or utilize external tools to verify the behavior of your webhook service. User our Webhoos API: To officially register your webhook service with the platform: Refer to the [Webhooks API](/api-reference/api-endpoints/webhooks) documentation for detailed guidance on setting up and managing your webhook configurations. Provide the required details such as endpoint URL, subscribed events, and optional secret key for validation. By following these steps, you can ensure a seamless integration and reliable handling of event notifications from the mio.ID platform. # Security Webhooks play a critical role in ensuring the seamless functionality of your integration. However, they can become targets for malicious actors attempting to exploit or disrupt the service. To safeguard your application, you must configure your webhook with a 32-byte secret. This secret is essential for encrypting the request body, adding a layer of security to the data transmission. ### Enabling Encryption When encryption is enabled in your webhook configuration: **Payload Format:** The webhook event payload is sent as text/plain containing encrypted data. \ \ **Initialization Vector (IV):** A 16-byte cipher initialization vector (IV) is included in the response headers as metadata. This IV is necessary to decrypt the webhook request body securely. Below you find an example process for decrypting an incoming webhook request: {% tabs %} {% tab title="TypeScript" %} ```typescript import * as crypto from 'crypto'; export class Decipher { decipherAES_256_CBC(request: any) { const CIPHER_KEY = 'YOUR-PLAIN-KEY'; const BASE64_PLAIN_IV = request.headers['x-pvt-cipher-iv']; const BASE64_CIPHERED_MESSAGE = request.body; const BUFFER_KEY = Buffer.from(CIPHER_KEY); const BUFFER_IV = Buffer.from(BASE64_PLAIN_IV, 'base64'); const BUFFER_CIPHERED_MESSAGE = Buffer.from(BASE64_CIPHERED_MESSAGE, 'base64'); const DECIPHER = crypto.createDecipheriv('aes-256-cbc', BUFFER_KEY, BUFFER_IV); DECIPHER.setAutoPadding(true); let deciphered_message = DECIPHER.update(BUFFER_CIPHERED_MESSAGE, 'hex', 'utf8'); deciphered_message += DECIPHER.final('utf-8'); return deciphered_message.toString(); } } ``` {% endtab %} {% endtabs %}