GuidesAPI ReferenceTry Ribbon!
Back to All

Adding Data Type Validation for Ribbon Fields

over 2 years ago by Wilfred Tso

📘

API updates are incremental!

By adding the new request header (see section "Accessing the New Version" below) for this update, you will automatically include updates from past API versions (i.e. 2021-05-13).

Overview

We have released an update to the Ribbon API that introduces data type validation to Ribbon fields.

This new feature checks the schema of the request body sent for editing fields or adding new records (e.g. insurances, locations).

This update affects the following endpoints:

  • PUT /v1/custom/providers/{npi}
  • PUT /v1/custom/providers/{npi}/locations/{uuid}
  • POST /v1/custom/insurances
  • PUT /v1/custom/insurances/{uuid}
  • POST /v1/custom/locations
  • PUT /v1/custom/locations/{uuid}

The purpose of this change is to ensure the validity and consistency of user edits to Ribbon's fields.

🚧

This is a potentially breaking change

If you are currently making use of data editing capabilities, there is a potential that you run into errors if you are making edits to fields that would be considered invalid per our definitions.

If you encounter validation errors, you can fix the error by passing through valid data per our definitions.

📘

This does not apply to custom fields you've added

Data Validation Definitions

We utilize the jsonschema standard (Draft7) for defining valid types the Ribbon fields. You can find the specification for jsonschema here.

We've defined schemas for Ribbon fields on providers, insurances, and locations:

{
    "type": "object",
    "properties": {
        "first_name": {"type": ["string", "null"]},
        "middle_name": {"type": ["string", "null"]},
        "last_name": {"type": ["string", "null"]},
        "age": {"type": ["integer", "null"]},
        "gender": {
            "enum": ["m", "f", None]
        },
        "ratings_count": {
            "type": ["integer", "null"],
            "minimum": 0
        },
        "ratings_avg": {
            "type": ["number", "null"],
            "minimum": 0,
            "maximum": 10
        },
        "degrees": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "provider_types": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "languages": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "online_profiles": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "url": {"type": ["string", "null"]}
                }
            }
        },
        "educations": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "type": {"type": ["string", "null"]},
                    "year": {"type": ["integer", "null"]},
                    "education": {
                        "type": "object",
                        "properties": {
                            "name": {"type": "string"},
                            "uuid": {"type": "string"}
                        }
                    }
                }
            }
        },
        "is_pcp": {"type": ["boolean", "null"]}
    }
}

{
    "type": "object",
    "properties": {
        "carrier_association": {"type": ["string", "null"]},
        "carrier_brand": {"type": ["string", "null"]},
        "carrier_name": {"type": ["string", "null"]},
        "state": {"type": ["string", "null"]},
        "plan_name": {"type": ["string", "null"]},
        "plan_type": {"type": ["string", "null"]},
        "metal_level": {"type": ["string", "null"]},
        "display_name": {"type": ["string", "null"]},
        "network": {"type": ["string", "null"]},
        "confidence": {
            "type": ["integer", "null"],
            "minimum": 0,
            "maximum": 5,
        },
        "category": {"type": ["string", "null"]},
        "codes": {
            "type": ["array", "null"],
            "items": {
                "type": "string"
            }
        }
    }
}

{
    "type": "object",
    "properties": {
        "name": {"type": ["string", "null"]},
        "address": {"type": "string"},
        "address_details": {
            "type": "object",
            "properties": {
                "street": {"type": ["string", "null"]},
                "address_line_1": {"type": ["string", "null"]},
                "address_line_2": {"type": ["string", "null"]},
                "city": {"type": ["string", "null"]},
                "state": {"type": ["string", "null"]},
                "zip": {"type": ["string", "null"]}
            }
        },
        "phone_numbers": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "phone": {"type": "string"},
                    "detail": {"type": "string"}
                }
            }
        },
        "location_types": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "npis": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "confidence": {
            "type": ["integer"],
            "minimum": 0,
            "maximum": 5,
        }
    }
}

Endpoints where Provider schema applies:

  • PUT /v1/custom/providers/{npi}

Endpoints where Insurance schema applies:

  • POST /v1/custom/insurances
  • PUT /v1/custom/insurances/{uuid}

Endpoint where Location schema applies:

  • POST /v1/custom/locations
  • PUT /v1/custom/locations/{uuid}
  • PUT /v1/custom/providers/{npi}/locations/{uuid}

🚧

Add Ribbon-Version: 2021-05-13 to every request header or email [email protected]

After you complete testing with the updated version, feel free to let us know and will set your entire API to this version. Email us at [email protected]

Alternatively, you can add Ribbon-Version: 2021-05-13 to every request header.

Note: a user interface to toggle API versions is in the works!