Rinkel MCP by usefulapi

List call detail records (inbound and outbound calls) with date, direction, status (ANSWERED, MISSED, VOICEMAIL, ANSWERING_SERVICE), duration, external and internal number, the users involved, notes, and (when the account has Rinkel AI insights) the AI summary and sentiment. Use for 'who called today', 'which calls did we miss this week', 'calls longer than 5 minutes'. Newest first by default. Rinkel API: GET /call-detail-records.

{
  "type": "object",
  "properties": {
    "filter": {
      "description": "Free-text search over calls.",
      "type": "string"
    },
    "internal_numbers": {
      "description": "Only calls on these internal (Rinkel) numbers, as listed by rinkel_list_numbers.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "external_number": {
      "description": "Only calls with this external (caller or callee) number.",
      "type": "string"
    },
    "date_preset": {
      "description": "A relative period. It overrides start_date and end_date.",
      "type": "string",
      "enum": [
        "TODAY",
        "THIS-WEEK",
        "LAST-TWO-WEEKS",
        "LAST-MONTH"
      ]
    },
    "start_date": {
      "description": "Only calls on or after this date (yyyy-mm-dd, or an ISO date-time with timezone). Sent as a Unix timestamp.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2}))?$"
    },
    "end_date": {
      "description": "Only calls on or before this date (yyyy-mm-dd = end of that day UTC, or an ISO date-time with timezone).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2}))?$"
    },
    "has_notes": {
      "description": "Only calls that have (true) or lack (false) notes.",
      "type": "boolean"
    },
    "is_anonymous": {
      "description": "Only calls from a hidden number (true) or not (false).",
      "type": "boolean"
    },
    "contact_lookup": {
      "description": "Include the matching contact in each record.",
      "type": "boolean"
    },
    "page": {
      "description": "Page number (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "description": "Items per page (default 10, max 50).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "directions": {
      "description": "Only these directions.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "INBOUND",
          "OUTBOUND"
        ]
      }
    },
    "statuses": {
      "description": "Only these call outcomes.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "MISSED",
          "ANSWERED",
          "VOICEMAIL"
        ]
      }
    },
    "user_ids": {
      "description": "Only calls handled by these user ids (rinkel_list_users).",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "sentiments": {
      "description": "Only calls with this AI-insights sentiment.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "POSITIVE",
          "NEGATIVE",
          "NEUTRAL"
        ]
      }
    },
    "duration_preset": {
      "description": "Duration buckets in minutes ('30-0' = 30 minutes or more). Overrides min/max duration.",
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "1-5",
          "5-15",
          "15-30",
          "30-0"
        ]
      }
    },
    "min_duration_seconds": {
      "description": "Minimum duration in seconds (ignored with duration_preset).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "max_duration_seconds": {
      "description": "Maximum duration in seconds (ignored with duration_preset).",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "has_transcription": {
      "description": "Only calls that have a transcription.",
      "type": "boolean"
    },
    "has_insights": {
      "description": "Only calls that have AI insights.",
      "type": "boolean"
    },
    "include_details": {
      "description": "Include insights and notes in each record.",
      "type": "boolean"
    },
    "contact": {
      "description": "Only calls with this contact (id).",
      "type": "string"
    },
    "sort": {
      "description": "Sort field (default date).",
      "type": "string",
      "enum": [
        "date",
        "duration",
        "status",
        "internalNumber",
        "externalNumber",
        "user"
      ]
    },
    "sort_order": {
      "description": "Sort order (default DESC).",
      "type": "string",
      "enum": [
        "ASC",
        "DESC"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one call detail record by its Rinkel id (the `id` field of rinkel_list_calls): numbers, users, status, duration, notes, voicemail and call-recording ids, AI insights. Rinkel API: GET /call-detail-records/{id}.

{
  "type": "object",
  "properties": {
    "call_record_id": {
      "type": "string",
      "minLength": 1,
      "description": "The call detail record id (`id`)."
    }
  },
  "required": [
    "call_record_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one call detail record by its network `callId` (the id Rinkel sends in webhook events), optionally with insights and notes. Rinkel API: GET /call-detail-records/by-call-id/{callId}.

{
  "type": "object",
  "properties": {
    "network_call_id": {
      "type": "string",
      "minLength": 1,
      "description": "The network call id (`callId` field)."
    },
    "include_details": {
      "description": "Include insights and notes.",
      "type": "boolean"
    }
  },
  "required": [
    "network_call_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get the raw transcription of a call by its network `callId` (needs Rinkel AI insights on the account; 404 when the call has none). Rinkel API: GET /call-detail-records/by-call-id/{callId}/transcription.

{
  "type": "object",
  "properties": {
    "network_call_id": {
      "type": "string",
      "minLength": 1,
      "description": "The network call id (`callId` field of the call record)."
    }
  },
  "required": [
    "network_call_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get a temporary URL (valid 3 hours) to stream or download a call recording. The id is `callRecording.id` of a call record. Append `download` as a query parameter to the URL to download instead of stream. Rinkel API: GET /call-recordings/{id}/stream.

{
  "type": "object",
  "properties": {
    "call_recording_id": {
      "type": "string",
      "minLength": 1,
      "description": "The call recording id (`callRecording.id` of a call record)."
    }
  },
  "required": [
    "call_recording_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List voicemail messages (call records with status VOICEMAIL): caller, date, duration, whether new, and the voicemail id. Newest first. With is_new=true Rinkel ignores every other filter and returns only unplayed voicemails. Rinkel API: GET /voicemails.

{
  "type": "object",
  "properties": {
    "filter": {
      "description": "Free-text search over calls.",
      "type": "string"
    },
    "internal_numbers": {
      "description": "Only calls on these internal (Rinkel) numbers, as listed by rinkel_list_numbers.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "external_number": {
      "description": "Only calls with this external (caller or callee) number.",
      "type": "string"
    },
    "date_preset": {
      "description": "A relative period (overrides start_date and end_date).",
      "type": "string",
      "enum": [
        "TODAY",
        "THIS-WEEK",
        "LAST-TWO-WEEKS",
        "LAST-MONTH"
      ]
    },
    "start_date": {
      "description": "Only calls on or after this date (yyyy-mm-dd, or an ISO date-time with timezone). Sent as a Unix timestamp.",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2}))?$"
    },
    "end_date": {
      "description": "Only calls on or before this date (yyyy-mm-dd = end of that day UTC, or an ISO date-time with timezone).",
      "type": "string",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}(T\\d{2}:\\d{2}(:\\d{2}(\\.\\d+)?)?(Z|[+-]\\d{2}:\\d{2}))?$"
    },
    "has_notes": {
      "description": "Only calls that have (true) or lack (false) notes.",
      "type": "boolean"
    },
    "is_anonymous": {
      "description": "Only calls from a hidden number (true) or not (false).",
      "type": "boolean"
    },
    "contact_lookup": {
      "description": "Include the matching contact in each record.",
      "type": "boolean"
    },
    "page": {
      "description": "Page number (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "description": "Items per page (default 10, max 50).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    },
    "is_new": {
      "description": "Only unplayed voicemails (true). All other filters are ignored then.",
      "type": "boolean"
    },
    "topics": {
      "description": "Only voicemails with these AI topic ids.",
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "sort_order": {
      "description": "Sort order by date (default DESC).",
      "type": "string",
      "enum": [
        "ASC",
        "DESC"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Number of voicemails that have not been played yet. Rinkel API: GET /voicemails/new-count.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get a temporary URL (valid 3 hours) to stream or download a voicemail. The id is `voicemail.id` of a call or voicemail record. Rinkel API: GET /voicemails/{id}/stream.

{
  "type": "object",
  "properties": {
    "voicemail_id": {
      "type": "string",
      "minLength": 1,
      "description": "The voicemail id (`voicemail.id`)."
    }
  },
  "required": [
    "voicemail_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the contacts shared with everyone in the account (plus the Rinkel system contact, tag 'system'): names, company, phone numbers, email. Rinkel API: GET /contacts.

{
  "type": "object",
  "properties": {
    "filter": {
      "description": "Search by name, company or number.",
      "type": "string"
    },
    "letter": {
      "description": "Only contacts whose name starts with this letter.",
      "type": "string",
      "minLength": 1,
      "maxLength": 1
    },
    "page": {
      "description": "Page number (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "description": "Items per page (default 10, max 50).",
      "type": "integer",
      "minimum": 1,
      "maximum": 50
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one contact by id. Rinkel API: GET /contacts/{id}.

{
  "type": "object",
  "properties": {
    "contact_id": {
      "type": "string",
      "minLength": 1,
      "description": "The contact id."
    }
  },
  "required": [
    "contact_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Find the contact that owns a phone number (E.164 such as +31612345678 works best). 404 when there is none. Rinkel API: GET /contacts/find-by-number/{number}.

{
  "type": "object",
  "properties": {
    "phone_number": {
      "type": "string",
      "minLength": 3,
      "maxLength": 40,
      "description": "The phone number, preferably in E.164 format (+31612345678)."
    }
  },
  "required": [
    "phone_number"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the account's users: name, email, phone number, role (ADMIN, USER, ANSWERINGSERVICE), availability schedule and status, and `fixed`/device info (`deviceId` is needed to start a call). Rinkel API: GET /users.

{
  "type": "object",
  "properties": {
    "include_avatars": {
      "description": "Include avatar URLs.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one user by id, including preferences, notification settings, schedule and `deviceId`. Rinkel API: GET /users/{id}.

{
  "type": "object",
  "properties": {
    "user_id": {
      "type": "string",
      "minLength": 1,
      "description": "The user id (rinkel_list_users)."
    },
    "include_avatar": {
      "description": "Include avatar URLs.",
      "type": "boolean"
    }
  },
  "required": [
    "user_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the account's Rinkel phone numbers: id, label, number, status (ACTIVE, SUSPENDED, PENDING_PORTING_IN ...), activation date and the users assigned. Rinkel API: GET /numbers.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Get one Rinkel number with its full dial plan: greeting, business hours schedule, call forwarding targets and ring logic, voice menu, call recording and caller-id settings. Rinkel API: GET /numbers/{id}.

{
  "type": "object",
  "properties": {
    "number_id": {
      "type": "string",
      "minLength": 1,
      "description": "The number id (rinkel_list_numbers)."
    }
  },
  "required": [
    "number_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the uploaded audio recordings used in the dial plan (greetings, announcements, voice-over scripts): name, description, duration and where each is used. Not call recordings. Rinkel API: GET /recordings.

{
  "type": "object",
  "properties": {
    "page": {
      "description": "Page number (default 1).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "per_page": {
      "description": "Items per page (default 10, max 999).",
      "type": "integer",
      "minimum": 1,
      "maximum": 999
    },
    "sort": {
      "description": "Sort field (default date).",
      "type": "string",
      "enum": [
        "date",
        "duration",
        "name",
        "description"
      ]
    },
    "sort_order": {
      "description": "Sort order (default DESC).",
      "type": "string",
      "enum": [
        "ASC",
        "DESC"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

List the webhook subscriptions (events incomingCall, outgoingCall, callStart, callEnd, callInsights) with URL and active flag. Webhooks need the Expert plan. Rinkel API: GET /webhooks.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Check a phone number for a country and return its normalised form. With check_inventory=true Rinkel also checks whether the number is available to order. Rinkel API: GET /misc/validate-phone-number.

{
  "type": "object",
  "properties": {
    "country_iso_code": {
      "type": "string",
      "pattern": "^[A-Za-z]{2}$",
      "description": "Country code such as NL or BE."
    },
    "number": {
      "type": "string",
      "minLength": 3,
      "maxLength": 40,
      "description": "The number without the country calling code."
    },
    "check_inventory": {
      "description": "Also check availability to order.",
      "type": "boolean"
    }
  },
  "required": [
    "country_iso_code",
    "number"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: add a note to a call record (visible to everyone in the account who sees the call). The id is the call record's `id`; if Rinkel answers 404, retry with the record's `callId`. Rinkel API: PUT /call-detail-records/{callId}/note.

{
  "type": "object",
  "properties": {
    "call_record_id": {
      "type": "string",
      "minLength": 1,
      "description": "The call record id (`id` of rinkel_list_calls)."
    },
    "content": {
      "type": "string",
      "minLength": 1,
      "maxLength": 5000,
      "description": "The note text."
    }
  },
  "required": [
    "call_record_id",
    "content"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: replace the text of an existing note on a call record (the note id is in `notes[].id` of the call record). Rinkel API: PATCH /call-detail-records/{callId}/note/{noteId}.

{
  "type": "object",
  "properties": {
    "call_record_id": {
      "type": "string",
      "minLength": 1,
      "description": "The call record id (`id`)."
    },
    "note_id": {
      "type": "string",
      "minLength": 1,
      "description": "The note id (`notes[].id`)."
    },
    "content": {
      "type": "string",
      "minLength": 1,
      "maxLength": 5000,
      "description": "The new note text."
    }
  },
  "required": [
    "call_record_id",
    "note_id",
    "content"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE, irreversible: delete one note from a call record. Needs confirm=true after the user approved it. Rinkel API: DELETE /call-detail-records/{callId}/note/{noteId}.

{
  "type": "object",
  "properties": {
    "call_record_id": {
      "type": "string",
      "minLength": 1,
      "description": "The call record id (`id`)."
    },
    "note_id": {
      "type": "string",
      "minLength": 1,
      "description": "The note id (`notes[].id`)."
    },
    "confirm": {
      "description": "Must be true, set only after the user explicitly approved this exact action.",
      "type": "boolean"
    }
  },
  "required": [
    "call_record_id",
    "note_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: create a contact. It is shared with everyone in the Rinkel account (all users see it and calls from its numbers show its name). Rinkel API: POST /contacts.

{
  "type": "object",
  "properties": {
    "first_name": {
      "type": "string",
      "maxLength": 100
    },
    "last_name": {
      "type": "string",
      "maxLength": 100
    },
    "company_name": {
      "type": "string",
      "maxLength": 200
    },
    "email": {
      "type": "string",
      "maxLength": 200
    },
    "numbers": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40,
            "description": "Label such as Mobile or Work."
          },
          "country_iso_code": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$",
            "description": "Country code such as NL."
          },
          "number": {
            "type": "string",
            "minLength": 3,
            "maxLength": 40,
            "description": "The number without the country calling code."
          }
        },
        "required": [
          "label",
          "country_iso_code",
          "number"
        ]
      },
      "description": "Phone numbers of the contact (Rinkel requires at least one)."
    },
    "default_outbound_number_id": {
      "description": "Id of the Rinkel number to call this contact from (rinkel_list_numbers).",
      "type": "string"
    }
  },
  "required": [
    "numbers"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: update a contact (PUT semantics). `numbers` is required and REPLACES all stored numbers, and an omitted default_outbound_number_id CLEARS it; omitted names, company and email keep their stored value. Read the contact first (rinkel_get_contact) and resend what must stay. The system contact cannot be changed. Rinkel API: PUT /contacts/{id}.

{
  "type": "object",
  "properties": {
    "contact_id": {
      "type": "string",
      "minLength": 1,
      "description": "The contact id."
    },
    "first_name": {
      "type": "string",
      "maxLength": 100
    },
    "last_name": {
      "type": "string",
      "maxLength": 100
    },
    "company_name": {
      "type": "string",
      "maxLength": 200
    },
    "email": {
      "type": "string",
      "maxLength": 200
    },
    "numbers": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "label": {
            "type": "string",
            "minLength": 1,
            "maxLength": 40,
            "description": "Label such as Mobile or Work."
          },
          "country_iso_code": {
            "type": "string",
            "pattern": "^[A-Za-z]{2}$",
            "description": "Country code such as NL."
          },
          "number": {
            "type": "string",
            "minLength": 3,
            "maxLength": 40,
            "description": "The number without the country calling code."
          }
        },
        "required": [
          "label",
          "country_iso_code",
          "number"
        ]
      },
      "description": "The COMPLETE list of numbers (replaces the stored ones; Rinkel requires at least one, so read the contact first and resend the ones to keep)."
    },
    "default_outbound_number_id": {
      "description": "Resend the current value to keep it; omit to clear it.",
      "type": "string"
    }
  },
  "required": [
    "contact_id",
    "numbers"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE, irreversible: delete a contact for the whole account. Needs confirm=true after the user approved it. The Rinkel system contact cannot be deleted. Rinkel API: DELETE /contacts/{id}.

{
  "type": "object",
  "properties": {
    "contact_id": {
      "type": "string",
      "minLength": 1,
      "description": "The contact id."
    },
    "confirm": {
      "description": "Must be true, set only after the user explicitly approved this exact action.",
      "type": "boolean"
    }
  },
  "required": [
    "contact_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: block a number from calling ANY of the account's numbers. Accepts an E.164 number, 'anonymous', or a prefix wildcard such as '+31*' (a wildcard must end the value and include a country code; a broad wildcard blocks every caller from that country). Undo with rinkel_unblock_number. Rinkel API: POST /privacy/block-number.

{
  "type": "object",
  "properties": {
    "number": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40,
      "description": "E.164 number (+31612345678), 'anonymous', or a prefix wildcard like '+3161*'."
    },
    "reason": {
      "description": "Why it is blocked (for example Spam).",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "number"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE: remove a number (or the same wildcard pattern that was blocked) from the block list so it can call again. Rinkel API: DELETE /privacy/unblock-number.

{
  "type": "object",
  "properties": {
    "number": {
      "type": "string",
      "minLength": 1,
      "maxLength": 40,
      "description": "The blocked entry exactly as it was blocked."
    }
  },
  "required": [
    "number"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

WRITE, COSTS CALL MINUTES: starts a real phone call. Rinkel rings the given user device first and, once it is answered, dials `to` using the chosen Rinkel number as caller id, so call charges apply to the account and the person called sees the number. Needs confirm=true, set only after the user explicitly asked to place this call. Get device_id from rinkel_list_users (`fixed`/device info or `deviceId`) and number_id from rinkel_list_numbers. Rinkel API: POST /dial.

{
  "type": "object",
  "properties": {
    "device_id": {
      "type": "string",
      "minLength": 1,
      "description": "The id of the user device that starts the call (`deviceId` of a user)."
    },
    "to": {
      "type": "string",
      "pattern": "^\\+[1-9]\\d{6,14}$",
      "description": "The number to call, in E.164 format (+31612345678)."
    },
    "number_id": {
      "type": "string",
      "minLength": 1,
      "description": "The id of the Rinkel number used as caller id (rinkel_list_numbers)."
    },
    "anonymous": {
      "description": "Hide the caller id (default false).",
      "type": "boolean"
    },
    "confirm": {
      "description": "Must be true, set only after the user explicitly approved this exact action.",
      "type": "boolean"
    }
  },
  "required": [
    "device_id",
    "to",
    "number_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}