> For the complete documentation index, see [llms.txt](https://docs.collegeai.com/latest/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.collegeai.com/latest/json-api/endpoints.md).

# Endpoints

This page contains the documentation for each endpoint, but if you're just getting started, we recommend taking a look at one of the guides e.g. Get College Information.

Note that all endpoints return JSON, even in the case of an error. The response will always have a `true` or `false` key named `success`.

```json
{
    "success": false,
    "message": "API Key was not provided"
}
```

{% hint style="warning" %}
Every request must include your API key.
{% endhint %}

### College Retrieval

## Get information for one or more colleges.

<mark style="color:blue;">`GET`</mark> `/v1/api/college/info`

See the college information guide for examples

Note that along with `info_ids`, **one** of `college_names`, `college_ids` or `college_unit_ids` must be provided

#### Query Parameters

| Name                                         | Type   | Description                                                                                                                                                                                                        |
| -------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| info\_ids	<mark style="color:red;">\*</mark> | String | <p>Comma-delimited <a href="/pages/YLJu1bHmnZAMcdaFDz0J">information ids</a>. Specifies what additional info to return in the response.</p><p>Example: <code>student\_faculty\_ratio,in\_state\_tuition</code></p> |
| college\_ids                                 | String | <p>Comma-delimited semantic ids for each college to query for.</p><p>Example: <code>rensselaer-polytechnic-institute,stanford-university</code></p>                                                                |
| college\_unit\_ids                           | String | <p>Comma-delimited <a href="/pages/UbXutYAb68LKissiNNvD">unit ids</a> for each college to query for.</p><p>Example: <code>194824,166683</code></p>                                                                 |
| college\_names                               | String | <p>Names or abbreviations for colleges to query for.</p><p>Example:</p><p><code>MIT,Rensselaer Polytechnic</code></p>                                                                                              |

{% tabs %}
{% tab title="200: OK Returns list of each college" %}

```json
{
  "success": true,
  "colleges": [
    {
      "collegeId": "rensselaer-polytechnic-institute",
      "collegeUnitId": "194824",
      "name": "Rensselaer Polytechnic Institute",
      "studentFacultyRatio": 15,
      "inStateTuition": 51000
    },
    {
      "collegeId": "stanford-university",
      "collegeUnitId": "243744",
      "name": "Stanford University",
      "studentFacultyRatio": 10,
      "inStateTuition": 48987
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Get a list of colleges matching a filter.

<mark style="color:blue;">`GET`</mark> `/v1/api/college-list`

#### Query Parameters

| Name                                        | Type   | Description                                                                                                                                                                                                        |
| ------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| info\_ids<mark style="color:red;">\*</mark> | String | <p>Comma-delimited <a href="/pages/YLJu1bHmnZAMcdaFDz0J">information ids</a>. Specifies what additional info to return in the response.</p><p>Example: <code>student\_faculty\_ratio,in\_state\_tuition</code></p> |
| limit                                       | Number | <p>Maximum number of colleges to return. Default max is 20.</p><p>Example: <code>20</code></p>                                                                                                                     |
| offset                                      | Number | <p>Use this when loading more on page scroll. Can be used to get more than the limit of colleges with multiple requests. Specifies what index to begin returning colleges at.</p><p>Example: <code>10</code></p>   |
| filters                                     | JSON   | <p>Object representing filters to apply on resultant colleges.</p><p>Example: See <a href="/pages/c7dFoeoVoXvrQcqol8b8">Filter Ids</a></p>                                                                         |

{% tabs %}
{% tab title="200: OK Returns list of colleges" %}

```json
{
  "success": true,
  "colleges": [
    {
      "collegeId": "university-of-california---berkeley",
      "collegeUnitId": "110635",
      "name": "University of California - Berkeley",
      "website": "www.berkeley.edu",
      "city": "Berkeley",
      "stateAbbr": "CA",
      "aliases": [
        "UC Berkeley"
      ],
    },
    {
      "collegeId": "university-of-california---los-angeles",
      "collegeUnitId": "110662",
      "name": "University of California - Los Angeles",
      "website": "www.ucla.edu",
      "city": "Los Angeles",
      "stateAbbr": "CA",
      "aliases": [
        "UCLA"
      ],
    }
  ]
}
```

{% endtab %}
{% endtabs %}

### Autocomplete

## Autocomplete college names based on query.

<mark style="color:blue;">`GET`</mark> `/v1/api/autocomplete/colleges`

Search for a college by name, location or abbreviation. Great for college search fields. See an example in the college information guide.

#### Query Parameters

| Name                                    | Type   | Description                                                         |
| --------------------------------------- | ------ | ------------------------------------------------------------------- |
| query<mark style="color:red;">\*</mark> | String | <p>Text to search colleges for.</p><p>Example: <code>RPI</code></p> |

{% tabs %}
{% tab title="200: OK Returns list of colleges" %}

```json
{
    "success": true,
    "collegeList": [
    {
      "id": "massachusetts-institute-of-technology",
      "unitId": 166683,
      "name": "Massachusetts Institute of Technology",
      "city": "Cambridge",
      "state": "MA"
    },
    {
      "id": "smith-college",
      "unitId": 167835,
      "name": "Smith College",
      "city": "Northampton",
      "state": "MA",
      "matchingIndices": [
        1,
        4
      ]
    },
    {
      "id": "hobart-william-smith-colleges",
      "unitId": 191630,
      "name": "Hobart William Smith Colleges",
      "city": "Geneva",
      "state": "NY",
      "matchingIndices": [
        16,
        19
      ]
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Autocomplete high school names based on query.

<mark style="color:blue;">`GET`</mark> `/vi/api/autocomplete/high-schools`

Great for high school search fields. This is useful if you have a form where a student should enter their high school.

#### Query Parameters

| Name                                | Type   | Description                                                                                                                       |
| ----------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------- |
| q<mark style="color:red;">\*</mark> | String | <p>The user's input to the form field or the name of the high school to search for.</p><p>Example: <code>San Francisco</code></p> |
| zipcode                             | String | <p>A zip code. This significantly improves selection recommendations.</p><p>Example: <code>94063</code></p>                       |