---
updatedAt: 2026-06-05T13:06:03.000Z
agentTools:
  projectIndex: https://ribbon.readme.io/llms.txt
---

# Create Location

Create new locations and facilities.

#### Example Use Case
You want to add new urgent care locations (or labs, imaging centers, therapy centers, etc.) to an area that are not yet included in the existing Ribbon locations listings.


# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "H1's API",
    "version": "1.0.0",
    "description": "An API for interacting with the data provided by Ribbon Health, including information about healthcare providers,\nlocations, insurances, and more.\n\n## Price Transparency v2\n\nLocation-first negotiated rate endpoints live under `/v2/*` (separate from legacy\n`/v1/pricing/*`). Use them to:\n\n1. Look up procedures, care clusters, and carriers (`GET /v2/procedures`,\n   `/v2/care-clusters`, `/v2/carriers`)\n2. Get prices for a known location (`GET /v2/locations/{location_id}/pricing/...`)\n3. Shop by geography (`GET /v2/pricing/locations/...`)\n\n**Key differences from v1:** prices are location-scoped (not provider-first);\ncarriers use string business ids (not v1 carrier UUIDs); every v2 response uses\nthe same envelope (`parameters`, `total_count`, `page`, `page_size`, `data`);\ngeo search requires an explicit `address` or `lat`+`lng` (no silent default).\n\nSee the **Price Transparency v2** tag for full endpoint reference.\n"
  },
  "servers": [
    {
      "url": "https://api.ribbonhealth.com"
    }
  ],
  "tags": [
    {
      "name": "Price Transparency v2",
      "description": "Location-first negotiated rates under `/v2/*`. Prefer these endpoints for new\nintegrations. Carrier ids come from `GET /v2/carriers` and are not interchangeable\nwith v1 pricing carrier UUIDs. Provider-scoped v2 routes are not live yet.\n"
    }
  ],
  "paths": {
    "/v1/custom/locations": {
      "post": {
        "summary": "Create Location",
        "description": "Create new locations and facilities.\n\n#### Example Use Case\nYou want to add new urgent care locations (or labs, imaging centers, therapy centers, etc.) to an area that are not yet included in the existing Ribbon locations listings.\n",
        "operationId": "postCustomLocations",
        "tags": [
          "Locations"
        ],
        "requestBody": {
          "required": true,
          "description": "A JSON object describing the location you want to create.",
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "uuid": {
                    "type": "string",
                    "format": "uuid",
                    "example": "f38b9fd5-1e28-4f6e-953c-1e1493b68e21",
                    "description": "A UUID uniquely identifying this location"
                  },
                  "name": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "address": {
                    "type": "string",
                    "example": "185 Berry St # 130, San Francisco, CA 94107, US"
                  },
                  "address_details": {
                    "type": "object",
                    "properties": {
                      "street": {
                        "type": "string",
                        "example": "185 Berry St # 130"
                      },
                      "address_line_1": {
                        "type": "string",
                        "example": "185 Berry St"
                      },
                      "address_line_2": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "example": "# 130"
                      },
                      "city": {
                        "type": "string",
                        "example": "San Francisco"
                      },
                      "state": {
                        "type": "string",
                        "example": "CA"
                      },
                      "zip": {
                        "type": "string",
                        "example": 94107
                      }
                    }
                  },
                  "latitude": {
                    "type": "number",
                    "example": 37.7765973
                  },
                  "longitude": {
                    "type": "number",
                    "example": -122.3919488
                  },
                  "google_maps_link": {
                    "type": "string",
                    "format": "url",
                    "example": "https://www.google.com/maps/@37.7765973-122.3919488?q=185%20Berry%20St%20%23%20130%2C%20SF%2C%20CA%2094107%2C%20US"
                  },
                  "phone_numbers": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "phone": {
                          "type": "string",
                          "example": 4155146410
                        },
                        "details": {
                          "type": "string",
                          "example": "primary"
                        }
                      }
                    }
                  },
                  "faxes": {
                    "type": "array",
                    "description": "Fax numbers associated with this location.\n\nThis property only appears for customers purchasing fax data. If you would like this property and are not receiving it, please reach out to support.\n",
                    "items": {
                      "type": "object",
                      "properties": {
                        "phone": {
                          "type": "string",
                          "example": 2121234567
                        },
                        "details": {
                          "type": "string",
                          "example": "secondary"
                        },
                        "confidence": {
                          "type": "integer",
                          "example": 3
                        }
                      }
                    }
                  },
                  "confidence": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "example": 2,
                    "description": "Each location contains a confidence score. This score indicates the probability of the given provider practicing at said location with the included contact information\n\nThis field will only be populated for Ribbon-provided locations. Locations you create yourself will have a confidence score of `null`.\n"
                  },
                  "insurances": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "description": "List of insurances UUIDs accepted at this location"
                  },
                  "tins": {
                    "type": "string",
                    "description": "Comma separated list of standard 9-digit identification code(s) used by the IRS for business entities and used for contracting and paying provider/facility claims.\n"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Location was successfully created.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "data"
                  ],
                  "properties": {
                    "data": {
                      "$ref": "#/paths/~1v1~1custom~1locations~1%7Blocation_uuid%7D/get/responses/200/content/application~1json/schema"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "This request attempted to update with invalid schema or was missing required fields.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/paths/~1v2~1carriers/get/responses/400/content/application~1json/schema"
                }
              }
            }
          },
          "409": {
            "description": "A location with this `address` and `name` pair already exists.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "Resource with given fields aready exists",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "status",
                        "code",
                        "message"
                      ],
                      "properties": {
                        "status": {
                          "type": "integer",
                          "example": 409
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "conflict"
                          ]
                        },
                        "message": {
                          "type": "string",
                          "enum": [
                            "resource already exists"
                          ]
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2/carriers": {
      "get": {
        "summary": "List Carriers (v2)",
        "description": "List carriers available in the Price Transparency v2 pricing data set.\n\nUse this to discover valid `carrier_id` values for pricing filters.\n\n#### Important\nThese identifiers are **not** the same as v1 [`/v1/pricing/carriers`](./getpricingcarriers)\nUUIDs. Always resolve carriers through this endpoint (or a curated customer\nmapping) when working with v2.\n",
        "operationId": "getV2Carriers",
        "tags": [
          "Price Transparency v2"
        ],
        "parameters": [
          {
            "name": "carrier_id",
            "in": "query",
            "required": false,
            "description": "Exact match on carrier business id.",
            "schema": {
              "type": "string",
              "example": "78110"
            }
          },
          {
            "name": "carrier_name",
            "in": "query",
            "required": false,
            "description": "Match on carrier display name. Case-insensitive substring on\n`/v2/carriers`; case-insensitive exact match on DB-backed pricing endpoints;\ncase-sensitive exact match on Elasticsearch search endpoints.\n",
            "schema": {
              "type": "string",
              "example": "Aetna"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page of results to return. Values below `1` are treated as `1`.\n",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 1,
              "example": 1
            }
          },
          {
            "name": "page_size",
            "in": "query",
            "required": false,
            "description": "Number of results per page. Hard-capped at **100**.\n",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20,
              "example": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching carriers.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "type": "object",
                      "description": "Standard response envelope for all Price Transparency v2 endpoints.\nPagination fields are always present; `parameters` echoes the non-null filters\nthat were applied (pagination keys are omitted from the echo).\n",
                      "required": [
                        "parameters",
                        "total_count",
                        "page",
                        "page_size",
                        "data"
                      ],
                      "properties": {
                        "parameters": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "Echo of non-null request filters (pagination omitted).",
                          "example": {
                            "code": "27447",
                            "code_scheme": "CPT"
                          }
                        },
                        "total_count": {
                          "type": "integer",
                          "description": "Total matching rows across all pages.",
                          "example": 1
                        },
                        "page": {
                          "type": "integer",
                          "description": "Current page number.",
                          "example": 1
                        },
                        "page_size": {
                          "type": "integer",
                          "description": "Page size used for this response.",
                          "example": 20
                        },
                        "data": {
                          "type": "array",
                          "description": "Records for the current page.",
                          "items": {}
                        }
                      }
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "An insurance carrier in the Price Transparency v2 data set.\nUse `carrier_id` as the filter value on pricing endpoints.\n",
                            "required": [
                              "carrier_id",
                              "name"
                            ],
                            "properties": {
                              "carrier_id": {
                                "type": "string",
                                "description": "Business id used in all v2 pricing filters.",
                                "example": "78110"
                              },
                              "name": {
                                "type": "string",
                                "description": "Display name.",
                                "example": "Aetna"
                              }
                            }
                          },
                          "example": [
                            {
                              "carrier_id": "78110",
                              "name": "Aetna"
                            }
                          ]
                        }
                      }
                    }
                  ]
                },
                "example": {
                  "parameters": {
                    "carrier_name": "aetna"
                  },
                  "total_count": 1,
                  "page": 1,
                  "page_size": 20,
                  "data": [
                    {
                      "carrier_id": "78110",
                      "name": "Aetna"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid query parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "description": "An error returned from the API",
                  "required": [
                    "error"
                  ],
                  "properties": {
                    "error": {
                      "type": "object",
                      "required": [
                        "status",
                        "code",
                        "message"
                      ],
                      "properties": {
                        "status": {
                          "type": "integer",
                          "description": "The HTTP error code associated with this error",
                          "example": 400
                        },
                        "code": {
                          "type": "string",
                          "enum": [
                            "invalid_query_params",
                            "bad_request"
                          ]
                        },
                        "message": {
                          "type": [
                            "object",
                            "string"
                          ],
                          "description": "An object representing what exactly went wrong. The keys available in this object vary with the type of error  returned.\n",
                          "example": {
                            "query": {
                              "_schema": [
                                "parameters 'npis' and 'location_ids' cannot be used together"
                              ]
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "The caller does not have Price Transparency access.",
            "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"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  },
  "security": [
    {
      "BearerAuth": []
    }
  ]
}
```