OpenAPI Specification
openapi: 3.2.0
info:
title: Ribbon Health TI Ns API
version: 1.0.0
description: 'An API for interacting with the data provided by Ribbon Health, including information about healthcare providers, locations, insurances, and more.
'
servers:
- url: https://api.ribbonhealth.com/v1
security:
- BearerAuth: []
tags:
- name: TINs
paths:
/custom/tin:
get:
summary: Search TINs
description: 'Search and list tins that exist within the Ribbon API.
'
operationId: getTins
tags:
- TINs
parameters:
- name: Tins Search Parameters
in: query
required: false
description: Search parameters for the tin reference endpoint.
explode: true
schema:
type: object
properties:
search:
type: string
description: 'String input that fuzzy searches across tins, name, address, and legal_name.
'
name:
type: string
description: 'The billing entity name that appears on claims data, or if available, the official legal name of the billing entity.
String input that is fuzzy matched against the `name` field.
Note: This parameter will not match with the `legal_name` field, only the `name` field.
'
legal_name:
type: string
description: 'The legal name of the entity associated with the TIN.
String input that is fuzzy matched against the `legal_name` field.
'
tin_ids:
type: string
description: 'Comma separated list of TINs.
Note: This parameter cannot be used in combination with any other parameters.
'
has_tin:
type: boolean
description: Boolean input that applies to tin_confirmed field.
page:
type: integer
description: The page of the results which was returned.
page_size:
type: integer
description: How many results are in each page.
responses:
'200':
description: Tins returned from a valid request
content:
application/json:
schema:
type: object
required:
- parameters
- tins
properties:
parameters:
oneOf:
- type: object
properties:
tin_ids:
type: string
description: Comma separated list of TINS.
- type: object
properties:
search:
type: string
description: String input that fuzzy searches across TINs, names, address, and legal_name.
name:
type: string
description: 'The billing entity name that appears on claims data, or if available, the official legal name of the billing entity.
String input that is fuzzy matched against the `name` field.
'
legal_name:
type: string
description: 'The legal name of the entity associated with the TIN.
String input that is fuzzy matched against the `legal_name` field.
'
has_tin:
type: boolean
description: Boolean input that applies to tin_confirmed field.
page:
type: integer
description: The page of the results which was returned.
page_size:
type: integer
description: The number of results per page.
tins:
type: array
description: array of returned TIN objects
items:
type: object
properties:
tin:
type: string
description: 'Standard 9-digit identification code used by the IRS for business entities and used for contracting and paying provider/facility claims.
'
name:
type: string
description: 'The billing entity name that appears on claims data, or if available, the official legal name of the billing entity.
'
legal_name:
type: string
description: The legal name of the entity associated with the TIN.
address:
type: string
description: 'The address of the organization with the TIN. This could be the primary service location or billing location.
'
tin_confirmed:
type: boolean
description: 'A yes/no field that assesses whether a TIN is likely to be valid or not. The field is powered by business logic that triangulates IRS data and claims data.
'
'403':
description: Trial accounts do not have access to custom tins
content:
application/json:
schema:
type: object
description: You are not allow to make this request
required:
- error
properties:
error:
type: object
required:
- status
- code
- message
properties:
status:
type: integer
example: 403
code:
type: string
enum:
- permission_denied
message:
type: string
example: a trial account does not have access to this functionality
/custom/tin/{tin_id}:
get:
summary: Get TIN
description: 'Retrieve data on a specific TIN.
'
operationId: getCustomTin
tags:
- TINs
parameters:
- name: tin_id
in: path
required: true
description: The target TIN.
schema:
type: string
format: uuid
example: 123454321
responses:
'200':
description: Returns a single TIN
content:
application/json:
schema:
type: object
properties:
tin:
type: string
description: Standard 9-digit identification code used by the IRS for business entities and used for contracting and paying provider/facility claims.
name:
type: string
description: The billing entity name that appears on claims data, or if available, the official legal name of the billing entity.
legal_name:
type: string
description: The legal name of the entity associated with the TIN.
address:
type: string
description: The address of the organization with the TIN. This could be the primary service location or billing location.
tin_confirmed:
type: boolean
description: A yes/no field that assesses whether a TIN is likely to be valid or not. The field is powered by business logic that triangulates IRS data and claims data.
'404':
description: The given TIN UUID cannot be found
content:
application/json:
schema:
type: object
description: The requested resource could not be found
required:
- error
properties:
error:
type: object
required:
- status
- code
- message
properties:
status:
type: integer
example: 404
code:
type: string
enum:
- not_found
message:
type: string
enum:
- resource not found
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer