API

Integrate with Hack Club Account's REST API

The Hack Club Account API allows you to retrieve user identity information after they've authorized your app via OAuth.

You may want to read the OAuth Guide first to get access tokens.

Authentication

Base URL

https://hca.dinosaurbbq.org

Endpoints

GET /api/v1/me

Get the authenticated user's identity information based on granted scopes.

GET /api/v1/me

Authentication: Required

Response:

{
  "identity": {
    "id": "ident!Zjnfyr",
    "ysws_eligible": true,
    "verification_status": "needs_submission",
    "first_name": "Heidi",
    "last_name": "Trashworth",
    "primary_email": "heidi69@hackclub.com",
    "slack_id": "U00000069",
    "phone_number": "+18028675309",
    "birthday": "2005-06-15",
    "legal_first_name": "Hakkuun",
    "legal_last_name": "[WOULDN'T YOU LIKE TO KNOW]",
    "addresses": [
      {
        "id": "addr!yxmu8b",
        "first_name": "Helena",
        "last_name": "Ackfoundation",
        "line_1": "8605 Santa Monica Blvd",
        "line_2": "PMB 86294",
        "city": "West Hollywood",
        "state": "CA",
        "postal_code": "90069",
        "country": "US",
        "primary": true
      }
    ]
  },
  "scopes": [
    "email",
    "name",
    "verification_status",
    "slack_id",
    "basic_info",
    "address",
    "legal_name"
  ]
}

Verification status values:
- needs_submission - User hasn't started verification
- pending - Verification is being reviewed
- verified - Successfully verified
- ineligible - Verification was rejected

GET /api/external/check

Check the verification status of a user by their ID, email, or Slack ID. This is a public endpoint that doesn't require authentication.

GET /api/external/check?email=orpheus@hackclub.com

Authentication: Not required

Parameters (provide one):
- idv_id - User's public ID (format: ident!xxxxx)
- email - User's email address
- slack_id - User's Slack ID

Response:

{
  "result": "verified_eligible"
}

Possible result values:
- needs_submission - User hasn't started verification
- pending - Verification is being reviewed
- verified_eligible - Verified and eligible for YSWS (under 18)
- verified_but_over_18 - Verified but over 18
- rejected - Verification was rejected
- not_found - No user found with the provided identifier

Available Scopes

When requesting OAuth authorization, you can request the following scopes:

Scope Description Community Access
email Access to email address ✅
name Access to first and last name ✅
slack_id Access to Slack ID ✅
verification_status Verification status and YSWS eligibility ✅
basic_info Email, name, verification status, birthday, phone HQ only
legal_name Legal first and last name HQ only
address Mailing addresses HQ only
set_slack_id Ability to associate Slack IDs HQ only, deprecated

Error Responses

Program-wide endpoints

GET /api/v1/identities/:id

Get a specific user's identity by their public ID.

GET /api/v1/identities/ident!abc123

Authentication: Program key required

Parameters:
- id (path) - The user's public ID (e.g., ident!abc123)

Response:

{
  "identity": {
    "id": "ident!Rqjfng",
    "first_name": "Heidi",
    "last_name": "Hacksworth"
  }
}

Fields returned depend on your program's configured scopes.

GET /api/v1/identities

List all identities that have authorized your application.

GET /api/v1/identities

Authentication: Program key required

Response:

{
  "identities": [
    {
      "id": "ident!RLwfr6",
      "first_name": "Heidi",
      "last_name": "Latta"
    },
    {
      "id": "ident!ZBKfAY",
      "first_name": "Heidi",
      "last_name": "Wofford"
    }
  ]
}