> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocketpunch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Profiles API: Search and Retrieve User Profile Data

> GET /api/v1/profiles — Retrieve Rocketpunch user profiles including experience, skills, and education with OAuth-authorized access.

The Profiles endpoint gives you access to Rocketpunch user profile data including professional headlines, skills, and current company affiliations. Public profile data is accessible using your App Key alone, making it straightforward to build candidate search, skill-matching, or directory features. For accessing private or user-specific profile information — such as contact details or non-public career history — your request must carry an OAuth access token obtained with the user's explicit consent.

## Endpoint

```
GET https://openapi.rocketpunch.com/api/v1/profiles
```

## Authentication

<Note>
  This endpoint supports two authentication modes depending on the data you need:

  * **App Key only** — Returns publicly available profile data. Suitable for search, discovery, and directory use cases.
  * **OAuth access token** — Returns additional profile fields authorized by the user, such as private career history or contact information.

  To set up OAuth and obtain user tokens, see the [OAuth Overview](/api/oauth/overview).
</Note>

## Request Headers

When authenticating with your App Key, include:

| Header         | Required           | Description                                           |
| -------------- | ------------------ | ----------------------------------------------------- |
| `X-RP-API-Key` | Yes (App Key mode) | Your App Key in the format `rp_app_xxxxxxxxxxxxxxxx`. |

When authenticating with an OAuth token on behalf of a user, replace the App Key header with:

| Header          | Required         | Description                                        |
| --------------- | ---------------- | -------------------------------------------------- |
| `Authorization` | Yes (OAuth mode) | Bearer token in the format `Bearer {oauth_token}`. |

## Query Parameters

<ParamField query="keyword" type="string">
  Search term for filtering profiles. Matched against user names, professional headlines, and listed skills. For example, `React`, `data scientist`, or `product designer`.
</ParamField>

<ParamField query="lang" type="string" default="ko">
  Language code for the response content. Common values are `ko` (Korean) and `en` (English). Rocketpunch supports 11 languages and returns a consistent schema regardless of language.
</ParamField>

<ParamField query="page" type="integer" default="1">
  The page number to retrieve. Page numbering starts at `1`.
</ParamField>

<ParamField query="per_page" type="integer">
  The number of profiles to return per page. Adjust this to suit the throughput and payload needs of your integration.
</ParamField>

## Example Request

<CodeGroup>
  ```javascript JavaScript theme={null}
  // App Key authentication — public profiles
  const response = await fetch(
    "https://openapi.rocketpunch.com/api/v1/profiles?keyword=React&lang=en",
    {
      method: "GET",
      headers: {
        "X-RP-API-Key": "rp_app_xxxxxxxxxxxxxxxx",
      },
    }
  );

  const data = await response.json();
  console.log(data.items);
  ```

  ```python Python theme={null}
  import requests

  url = "https://openapi.rocketpunch.com/api/v1/profiles"
  params = {
      "keyword": "React",
      "lang": "en",
  }
  headers = {
      # Use X-RP-API-Key for public data, or Authorization for OAuth
      "X-RP-API-Key": "rp_app_xxxxxxxxxxxxxxxx",
  }

  response = requests.get(url, params=params, headers=headers)
  data = response.json()
  print(data["items"])
  ```

  ```bash cURL theme={null}
  # App Key authentication — public profiles
  curl -G "https://openapi.rocketpunch.com/api/v1/profiles" \
    --data-urlencode "keyword=React" \
    --data-urlencode "lang=en" \
    -H "X-RP-API-Key: rp_app_xxxxxxxxxxxxxxxx"

  # OAuth authentication — user-authorized profile data
  curl -G "https://openapi.rocketpunch.com/api/v1/profiles" \
    --data-urlencode "keyword=React" \
    --data-urlencode "lang=en" \
    -H "Authorization: Bearer {oauth_token}"
  ```
</CodeGroup>

## Response

A successful request returns HTTP `200` with a JSON body containing a paginated list of user profile objects under the `items` key.

```json theme={null}
{
  "items": [
    {
      "handle": "jane-doe",
      "name": "Jane Doe",
      "headline": "Frontend Engineer · React · TypeScript",
      "skills": ["React", "TypeScript", "Next.js", "GraphQL"],
      "current_company": {
        "name": "Rocketpunch Labs",
        "handle": "rocketpunch-labs"
      }
    }
  ],
  "total": 512,
  "page": 1,
  "per_page": 20
}
```

<Note>
  The field values shown above are illustrative examples. Profile data is subject to each user's individual privacy settings. Fields may be `null` or absent for profiles where the user has not made that information public, or where OAuth consent has not been granted for private fields.
</Note>

### Response Fields

<ResponseField name="items" type="array" required>
  An array of user profile objects matching your query. Returns an empty array if no profiles match.

  <Expandable title="Profile object fields">
    <ResponseField name="items[].handle" type="string">
      The URL-safe handle for the user's Rocketpunch profile. You can construct a direct link using `https://www.rocketpunch.com/@{handle}`.
    </ResponseField>

    <ResponseField name="items[].name" type="string">
      The user's display name. May be `null` if the user has restricted name visibility in their privacy settings.
    </ResponseField>

    <ResponseField name="items[].headline" type="string">
      A short professional headline provided by the user, typically describing their role, expertise, or key skills.
    </ResponseField>

    <ResponseField name="items[].skills" type="array of strings">
      A list of skills the user has added to their profile. Returns an empty array if the user has not listed any skills, or if skills are not publicly visible.
    </ResponseField>

    <ResponseField name="items[].current_company" type="object">
      A summary of the user's current employer as listed on their profile. Returns `null` if the user has not provided current employment information.

      <Expandable title="Current company fields">
        <ResponseField name="items[].current_company.name" type="string">
          The display name of the user's current employer.
        </ResponseField>

        <ResponseField name="items[].current_company.handle" type="string">
          The Rocketpunch handle of the current employer, usable with the [Companies API](/api/reference/companies) for additional context.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="total" type="integer" required>
  The total number of profiles matching your query across all pages.
</ResponseField>

<ResponseField name="page" type="integer" required>
  The current page number reflected in this response.
</ResponseField>

<ResponseField name="per_page" type="integer" required>
  The number of results per page reflected in this response.
</ResponseField>

## Error Responses

| HTTP Status                 | Meaning                                                                                                        |
| --------------------------- | -------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`          | Your `X-RP-API-Key` or OAuth token is missing or invalid.                                                      |
| `403 Forbidden`             | You attempted to access private profile data without a valid OAuth token, or the user has not granted consent. |
| `429 Too Many Requests`     | You have exceeded your plan's rate limit.                                                                      |
| `500 Internal Server Error` | An unexpected server-side error occurred. Retry with exponential backoff.                                      |

<Warning>
  Profile data is personal information. You must handle all data returned by this endpoint in accordance with applicable privacy laws and Rocketpunch's API Terms of Service. Do not cache or store user profile data beyond what is necessary for your application's stated purpose.
</Warning>