MOK Integration API (v1)

OAuth2 endpoint to obtain an access token using client credentials flow. The access token must be included in all subsequent API requests in the Authorization header.

Example:

Authorization: Bearer your_access_token

Flow

sequenceDiagram
    autonumber
    participant C as Your app
    participant A as Authorization server
    participant API as Provider Network API
    C->>A: POST /oauth/token (grant_type=client_credentials, scope=provider_networks)
    A->>A: Validate client_id and client_secret
    A-->>C: 200 with access_token, token_type Bearer, expires_in
    Note over C: Reuse the token until it expires
    C->>API: GET a provider_networks endpoint with header Authorization Bearer token
    API-->>C: 200 resource

Retrieves information about the authenticated provider network, including their services that are present in this specific application, and your configured webhook_url.

Webhook Notifications

Service request events are delivered to your configured webhook_url. Rendered API docs also show each event as a dedicated Webhooks entry with its full payload schema.

Events

• service_request.created: a service request was created from one of our platforms.
• service_request.updated: a service request was updated from one of our platforms.

Payload

{
  "event": "service_request.created",
  "payload": { ...service request (see the Service Requests schema for all fields) }
}

Security

Each request includes an X-Signature header: an HMAC-SHA256 hex digest of the raw request body, keyed with your webhook_secret. A Webhook-From header carries the sending host. Verify the signature before trusting the payload:

signature = request.headers['X-Signature']
expected  = OpenSSL::HMAC.hexdigest('SHA256', webhook_secret, request.raw_post)
valid     = ActiveSupport::SecurityUtils.secure_compare(signature, expected)

Authentication (optional, configured per provider network)

Requests may also carry credentials via HTTP Basic, a static Bearer token, or a Bearer token fetched from a configured auth URL. Contact us to set or change your webhook_url, secret, or auth mode.

Returns a list of contracts associated with the provided document identifier (DNI, mobile phone number, or access code), national ID, email, ID or access identifier. Each contract includes the customer's personal information, contract dates, and available services so you can validate them before creating a service request.

Important: The contract id and service id returned in this response are required to create a service request.

Important

• The document_identifier field is deprecated and will be removed in the future.
• The access_identifier field is the new field that will be used to identify the contract.

Service Limits

Each service includes a limits object that describes usage restrictions for the user. The limits field is only present when searching by access_identifier or document_identifier.

Limit Types

• usage_frequency_by_end_of_contract: Maximum number of uses allowed until the contract ends.
• usage_frequency_by_period: Maximum number of uses allowed per period (e.g., monthly).
• waiting_period: Time the user must wait before using the service.
• max_cost_by_end_of_contract: Maximum cost allowed until the contract ends.
• max_cost_by_period: Maximum cost allowed per period.
• max_cost_by_use: Maximum cost allowed per single use.
• copayment: Copayment amount required for the service.
• variable_copayment_by_days_of_current_service_request: Copayment that varies based on the number of days of the current service request, defined by tiers.
• variable_copayment_by_usage_by_period: Copayment that varies based on usage within a period, defined by tiers.
• variable_copayment_by_accumulated_days_by_period: Copayment that varies based on accumulated days within a period, defined by tiers.

Interpreting Limit Values

• multiplans_limit: The maximum allowed value (uses or cost).
• multiplans_limit_progress: Current usage towards the limit.
• block_service: If true, the user cannot use this service (limit exceeded or waiting period active).
• multiplans_until_date: Date until which the limit applies (format: dd/mm/yyyy).
• copayment_tiers: Array of tiers describing the copayment structure for variable copayment limits. Only present for variable_copayment_* limit types.

Quick Check

• Use has_any_limits to check if any limits are configured for the service.
• Use block_service (at the root level) to check if the service is blocked due to any limit.

Returns a list of plans. Only services owned by the logged in provider network are included in each plan.

Retrieves all service requests associated with the logged in provider network.

Important

• The document_identifier field is deprecated and will be removed in the future.
• The access_identifier field is the new field that will be used to identify the contract.
• The access_identifier_kind field is the kind of the access identifier. It can be national_id, mobile_phone_number, email, phone_number or access_code.

Creates a new service request for a user. This endpoint allows creating service requests for contracts that were previously validated using the contracts endpoint or by providing a document identifier or access identifier that matches an existing contract.

Important:

• A valid service is required and must be provided either by including the service_id parameter or by providing a service_external_id that matches an existing service's external ID.
• If both service_id and service_external_id are provided, the service_external_id will have priority.
• A valid contract is required and must be provided either by including the contract_id or by providing a access_identifier or document_identifier that matches an existing contract.
• The external_id is an optional field that can be used to link the service request to your internal reference ID.

Important

• The document_identifier field is deprecated and will be removed in the future.
• The access_identifier field is the new field that will be used to identify the contract.

Accepted fields

service_id, contract_id, external_id, current_status, access_identifier, requested_at, service_name, origin_address, origin_latitude, origin_longitude, destination_address, destination_latitude, destination_longitude, scheduled_date, scheduled_end_date, scheduled_time, provider_name, provider_phone, technician_name, user_phone, source, contact_center_phone, service_external_id

Flow

sequenceDiagram
    autonumber
    participant C as Your app
    participant API as Provider Network API
    C->>API: POST /service_requests with header Authorization Bearer token
    API->>API: Resolve the service and validate the request
    API-->>C: 201 service_request
    Note over C,API: Requests you create through the API do not send a webhook back to you

Retrieves a specific service request by its ID.

Updates an existing service request. This endpoint allows updating certain fields of a service request after it has been created.

Important:

• Some fields like service_id and contract_id cannot be modified after creation

Important

• The document_identifier field is deprecated and will be removed in the future.
• The access_identifier field is the new field that will be used to identify the contract.

Accepted fields

external_id, current_status, service_name, origin_address, origin_latitude, origin_longitude, destination_address, destination_latitude, destination_longitude, scheduled_date, scheduled_end_date, scheduled_time, provider_name, provider_phone, technician_name, user_phone, contact_center_phone

Flow

sequenceDiagram
    autonumber
    participant C as Your app
    participant API as Provider Network API
    C->>API: PATCH /service_requests/{id} with header Authorization Bearer token
    API->>API: Apply the update
    API-->>C: 200 service_request

Receives a request to send a WhatsApp message.

The whatsapp_number parameter is required.

The whatsapp_number must be a valid number according to the E.164 standard.

Flow

sequenceDiagram
    autonumber
    participant C as Your app
    participant API as Provider Network API
    participant WA as WhatsApp provider
    participant U as End user
    C->>API: POST /whatsapp/send with a whatsapp_number
    API->>API: Normalize and validate the E.164 number
    API->>WA: Send the opening WhatsApp message
    WA->>U: Message delivered to the end user's phone
    API-->>C: 200 message sent successfully

Sent to your configured webhook_url whenever a service request is created from one of our platforms. Your endpoint should respond with a 2xx status to acknowledge receipt; non-2xx responses are retried with exponential backoff.

Security

Every request includes an X-Signature header: an HMAC-SHA256 hex digest of the raw request body, keyed with your webhook_secret. Verify it before trusting the payload:

signature = request.headers['X-Signature']
expected  = OpenSSL::HMAC.hexdigest('SHA256', webhook_secret, request.raw_post)
valid     = ActiveSupport::SecurityUtils.secure_compare(signature, expected)

Authentication (optional, configured per provider network)

In addition to the signature, requests may carry credentials in one of these modes:

• Basic — HTTP Basic Authorization header with your username/password.
• Bearer (static) — a fixed bearer token that does not expire.
• Bearer (fetched) — we POST your username/password to a configured auth URL and use the returned token. The JSON keys for username, password and token are configurable.

To change your webhook_url, webhook_secret, or auth mode, contact us at devs-moklabs@grupomok.com.

Flow

sequenceDiagram
    autonumber
    participant P as MOK platform (web app)
    participant MOK as Provider Network API
    participant Q as Background worker
    participant W as Your webhook_url
    P->>MOK: A service request is created or updated on a MOK platform
    MOK->>Q: Enqueue webhook delivery job
    Q->>W: POST event and payload with headers X-Signature and Webhook-From
    W->>W: Compute HMAC-SHA256 of the raw body keyed with webhook_secret
    W->>W: Compare the result against the X-Signature header
    alt signature valid
        W-->>Q: 2xx acknowledge
    else invalid or processing error
        W-->>Q: non-2xx
        Note over Q,W: Delivery is retried with exponential backoff
    end

Sent to your configured webhook_url whenever a service request is updated from one of our platforms (for example, a status change). The signature, authentication and acknowledgement rules are identical to service_request.created above.

Returns every contract known to the application.

Creates a contract, or updates the active contract that matches the given application_code (plan code) and access_identifier. When an active contract exists with a different client_contract, a new contract is created instead of updating the existing one.

The response new_contract? flag tells you whether a contract was created or updated, and success? / errors report validation results.

Creates or updates many contracts in a single request. Each item follows the same rules as create_or_update. The response returns one contract object per item, each carrying its own success? / errors, so partial failures can be inspected without failing the whole batch.

Returns every point transaction.

Adds or spends points for the user identified by access_identifier. The transaction is processed asynchronously.

Schedules a rule that issues point transactions on a recurring cadence defined by recurrence_period (an ISO 8601 duration such as P1D or P1M).

Returns the providers ranked for a given zone and service, scoped to the authenticated provider network.

Both zone_external_id and service_external_id are required; omitting either returns a 422 with detail missing_required_params.

Flow

sequenceDiagram
    autonumber
    participant C as Your app
    participant M as mok-services
    Note over C,M: Served from the central host mokservices.moklabs.com, not your per-sponsor host
    C->>M: GET /providers/ranking with zone_external_id and service_external_id
    M->>M: Rank the providers for that zone and service
    M-->>C: 200 with a providers list (position, provider_name, external_id)