← Back to Guildbase

Guildbase REST API

A guild-scoped REST API for reading and managing your applications, members, roles and exams programmatically. All endpoints are versioned under /api/v1 and return JSON.

Base URL

https://guildbase.gg/api/v1

Auth

Bearer API key (Pro)

Rate limit

120 requests / minute / key

Authentication

Create an API key in Guild Settings → API Keys (requires a Pro subscription). Pass it as a Bearer token on every request. Keys are shown only once at creation — store them securely and never expose them in client-side code.

curl https://guildbase.gg/api/v1/me \
  -H "Authorization: Bearer gb_live_your_key_here" \
  -H "Accept: application/json"

A missing or invalid key returns 401:

{ "success": false, "error": "missing_api_key", "message": "API key is required. Use Authorization: Bearer <api_key>" }

Scopes

Each key is granted a set of scopes when it is created. A request to an endpoint whose scope the key lacks returns 403 insufficient_scope. The scope required by each endpoint is listed in the reference below.

guild:read Read guild profile
applications:read Read applications & templates
applications:write Approve, reject, move & delete applications
members:read Read guild members
members:write Add, update & remove members
roles:read Read guild roles
roles:write Create, update & delete roles
exams:read Read exams, attempts & certificates
exams:write Revoke certificates
staff:review Let in-game staff review applications as themselves

Requests

Pagination

List endpoints are paginated. Use ?page= and ?per_page= (1–100, default 25). Every list response carries a meta object:

"meta": {
  "current_page": 1,
  "per_page": 25,
  "total": 128,
  "last_page": 6,
  "has_more": true
}

Rate limit headers

Responses include X-RateLimit-Limit and X-RateLimit-Remaining. When throttled you receive 429 with a Retry-After header.

Responses

Every response is wrapped in a consistent envelope.

Single object

{
  "success": true,
  "data": { "id": 1, "name": "..." }
}

Paginated list

{
  "success": true,
  "data": [ { "id": 1, ... }, { "id": 2, ... } ],
  "meta": { "current_page": 1, "per_page": 25,
            "total": 42, "last_page": 2, "has_more": true }
}

Fields marked "omitted" in the object reference are only present when the related data is loaded for that endpoint (for example, answers appears only on GET /applications/{id}).

Errors

Errors use the same envelope with success: false, a stable error code, and a human-readable message. Integrate against the code, not the message text.

Status Error code When it happens
401 missing_api_key No Authorization header, or it is not a Bearer token.
401 invalid_api_key_format The token does not begin with gb_live_.
401 invalid_api_key The token does not match any key.
401 api_key_invalid The key is inactive or has expired.
403 pro_required The guild that owns the key does not have an active Pro subscription.
403 insufficient_scope The key is valid but lacks the scope the endpoint requires.
403 template_not_published POST /sessions — the template is a draft, scheduled, closed or full. The current state is returned as template_status.
403 template_locked POST /sessions — the template is disabled by the guild's plan limit (e.g. after a downgrade).
404 not_found The resource does not exist, or belongs to a different guild.
404 template_not_found POST /sessions — no template in this guild matches the template_slug / template_id sent. List your templates with GET /api/v1/templates and copy the exact slug.
404 invalid_session POST /sessions/check — the session token does not exist.
410 session_invalid POST /sessions/check — the session has expired or has already been used.
405 method_not_allowed The HTTP verb is not supported for this path.
403 not_staff Staff endpoints — the discord_id sent has no Guildbase account, or is not a team member of this guild.
403 staff_locked Staff endpoints — the team member is above the guild's plan limit, so their permissions are suspended.
403 insufficient_permission Staff endpoints — the staff member's guild role does not grant the permission the action needs. The required permissions are returned as required_permissions.
403 template_forbidden Staff endpoints — the staff member does not have access to this application's template.
403 pro_required POST /staff/applications/{id}/ai-check — AI detection requires Pro.
409 already_final Conflict — e.g. approving an application that is already accepted/rejected.
409 already_claimed POST /staff/applications/{id}/claim — another staff member holds the claim.
409 cannot_withdraw POST /ingame/applications/{id}/withdraw — the application has already been decided.
409 cannot_advance POST /staff/applications/{id}/advance — there is no next stage.
409 cannot_push_back POST /staff/applications/{id}/pushback — the application is past its initial stage.
409 not_final POST /staff/applications/{id}/overturn — the application has not been accepted or rejected.
422 validation_failed The request body failed validation. Includes an errors object.
429 rate_limited Rate limit exceeded (120 requests / minute / key).
500 server_error An unexpected error occurred on our side.

Insufficient scope (403)

{
  "success": false,
  "error": "insufficient_scope",
  "message": "This API key is missing the required scope: members:write.",
  "required_scopes": ["members:write"]
}

Validation failed (422)

{
  "success": false,
  "error": "validation_failed",
  "message": "The given data was invalid.",
  "errors": {
    "stage_id": ["The stage id field is required."]
  }
}

In-game sessions

In-game scripts (FiveM, launchers, kiosks) let a player apply without signing in through Discord. Your script creates a session for the player's Discord id, then opens the returned embed_url in a browser or NUI frame. Sessions are single-use and expire after 1 hour.

1. Look up the template slug

Do this once, not on every request. Template slugs are generated with a random suffix (staff-application-a1b2c3) unless you set a custom slug in Template Settings — guessing a friendly name such as staff-app is the most common cause of 404 template_not_found.

curl https://guildbase.gg/api/v1/templates \
  -H "Authorization: Bearer gb_live_your_key_here" \
  -H "Accept: application/json"

2. Create the session

curl -X POST https://guildbase.gg/api/v1/sessions \
  -H "Authorization: Bearer gb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"template_slug":"staff-application-a1b2c3","discord_id":"584378000000000000"}'
{
  "success": true,
  "session_token": "...",
  "embed_url": "https://guildbase.gg/embed/apply/your-guild/staff-application-a1b2c3?s=...",
  "expires_at": "2026-01-01T12:00:00+00:00",
  "template": { "id": 12, "name": "Staff Application", "slug": "staff-application-a1b2c3" }
}

3. Open the embed URL

Open embed_url verbatim — the ?s= token is what authenticates the player, so building the URL yourself will not work. Once the application is submitted the session is consumed; create a new one for the next player.

Troubleshooting a failed session request

  • 404 template_not_found — the slug or id does not exist in the guild that owns the API key. Re-check step 1; the response repeats the value it received as template_identifier.
  • 403 template_not_published — the template exists but is not live. The response includes template_status (draft, scheduled, closed, full).
  • 401 — the key is missing, malformed, inactive or expired.
  • 403 pro_required — the guild's Pro subscription is not active.
  • 422 validation_failed — usually discord_id; it must be the numeric id, not a username.

Log the response body, not just the status code — every error carries a message explaining the cause.

In-game staff review

The /api/v1/staff/* endpoints let your staff read and action applications from inside your game server — the same decisions, stage moves, pushbacks, claims, overturns and AI scans as the reviewer dashboard. They exist as a separate group because they behave differently from the rest of the API: instead of acting as the key, every request names the staff member taking the action.

Why that matters

One game server holds one key, but a dozen people take turns using it. So each request carries the acting staff member's discord_id, and Guildbase enforces that person's guild role and template access — not the key's. A reviewer who cannot reject on the website cannot reject from a game server either, and the application timeline names the person rather than the integration.

1. Create a key with the staff:review scope

In Guild Settings → API Keys, tick staff:review. It is not granted by default. One key per guild: if your staff work across several guilds, your integration holds one key for each and asks all of them who the player is.

2. Ask each key who the player is

curl "https://guildbase.gg/api/v1/staff/resolve?discord_id=584378000000000000" \
  -H "Authorization: Bearer gb_live_your_key_here" \
  -H "Accept: application/json"
{
  "success": true,
  "data": {
    "guild": { "id": 42, "name": "Los Santos RP", "slug": "los-santos-rp", "logo_url": "..." },
    "staff": { "id": 8, "username": "hr_lead", "discord_id": "584378000000000000", "is_owner": false,
               "role": { "id": 4, "name": "Moderator", "color": "#22c55e" } },
    "permissions": { "view": true, "manage": true, "review": true, "overturn": false,
                     "delete": false, "analytics": true, "claim": true, "ai_check": true },
    "counts": { "total": 128, "open": 6, "flagged": 2 },
    "templates": [ { "id": 7, "name": "Police Whitelist" } ]
  }
}

A 403 not_staff means that Discord account has no access to that guild — skip it and keep the guilds that answered 200. If only one does, open straight into it; if several do, let the player pick.

3. List, open and action

Pass discord_id on every call — as a query parameter on the GETs and in the JSON body on the rest.

curl "https://guildbase.gg/api/v1/staff/applications?discord_id=584378000000000000&status=pending" \
  -H "Authorization: Bearer gb_live_your_key_here"

curl -X POST "https://guildbase.gg/api/v1/staff/applications/9b1deae4-2f6a-4c1e-9a0b-2e5f7c3a11d2/reject" \
  -H "Authorization: Bearer gb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"discord_id":"584378000000000000","reason":"Please re-apply in 14 days."}'

Which permission each action needs

  • applications.view — list, open, run an AI check
  • applications.manage — move, advance
  • applications.review — approve, reject, push back
  • applications.overturn — overturn a final decision
  • applications.delete — permanently delete
  • applications.review or applications.manage — claim and unclaim

resolve and the detail endpoint both return a permissions object, so your UI can hide what the person cannot do instead of showing buttons that return 403 insufficient_permission.

Our FiveM resource implements all of this behind a /apps command.

In-game phone mail

Guildbase emails an applicant and DMs them on Discord. Neither reaches somebody who is in a game right now with the browser tab closed and Discord minimised — which is exactly when a decision on their whitelist matters most to them. The /api/v1/ingame/* endpoints let a game server deliver the same notice to the phone they are already holding.

Why your server polls us

A game server sits behind whatever NAT its host put it behind and has no stable address we could post to, so nothing is pushed. We queue the notification; your server asks for it on its own schedule, for the players it currently has online. We hold an undelivered notice for 24 hours, so somebody who gets a decision while offline still receives it when they next log in.

What gets queued

Collecting it

curl -X POST https://guildbase.gg/api/v1/ingame/mail \
  -H "Authorization: Bearer gb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"discord_ids":["584378000000000000","329110000000000000"]}'

A notice is marked delivered the moment it is handed over, so a second poll will not return it again. Poll on a timer with the Discord ids of whoever is online; there is no cost to an empty answer.

A player's own applications

The same group lets a player see what they have submitted and withdraw one that has not been decided — the same rule as the website, only while it is submitted or in_review. Every endpoint here is confined to one Discord id and will not return or touch anybody else's application.

curl "https://guildbase.gg/api/v1/ingame/applications?discord_id=584378000000000000" \
  -H "Authorization: Bearer gb_live_your_key_here"

These need no scope beyond a valid key — the same key that drives your application NPCs drives all of it. Our FiveM resource implements the lot, delivering to LB Phone and exposing a /myapps command.

Endpoints

Introspection

GET /api/v1/me

Details about the current API key: guild, scopes and usage.

Returns: Key & guild metadata

GET /api/v1/guild guild:read

The guild this key is scoped to.

Returns: A Guild object

In-Game Sessions

POST /api/v1/sessions

Create a short-lived session so a player can fill in an application from inside your game/server (FiveM NUI, launcher, kiosk) without a Discord OAuth login. Returns an embed_url to open in the browser/NUI.

Parameter In Type Required Description
template_slug body string conditional Slug of the template to apply for. Required unless template_id is given. Copy it from GET /api/v1/templates — generated slugs end in a random suffix (e.g. staff-application-a1b2c3).
template_id body integer conditional Template id. Required unless template_slug is given.
discord_id body string required Discord user id of the player (digits only, max 20). The submitted application is attributed to this Discord account.

Returns: { session_token, embed_url, expires_at, template }

POST /api/v1/sessions/check

Check whether a session token is still valid (not expired, not yet used).

Parameter In Type Required Description
session_token body string required The session_token returned by POST /api/v1/sessions.

Returns: { session: { discord_id, template_id, expires_at } }

Application Templates

GET /api/v1/templates applications:read

List application templates for the guild.

Parameter In Type Required Description
is_active query boolean optional Filter to active/inactive templates only.
page query integer optional Page number (default 1).
per_page query integer optional Items per page, 1–100 (default 25).

Returns: Paginated list of ApplicationTemplate objects

GET /api/v1/templates/{id} applications:read

Retrieve a single template.

Returns: An ApplicationTemplate object

Applications

GET /api/v1/applications applications:read

List applications for the guild.

Parameter In Type Required Description
status query string optional Filter by status (pending, in_review, accepted, rejected, withdrawn).
template_id query integer optional Filter by application template id.
risk_level query string optional Filter by risk level (low, medium, high).
claimed query boolean optional Only claimed (true) or unclaimed (false) applications.
sort query string optional submitted_at (default) or created_at.
direction query string optional asc or desc (default).
page query integer optional Page number.
per_page query integer optional Items per page, 1–100.

Returns: Paginated list of Application objects (without answers)

GET /api/v1/applications/{id} applications:read

Retrieve one application, including its formatted answers.

Returns: An Application object (with answers)

POST /api/v1/applications/{id}/approve applications:write

Approve the application — moves it to the workflow's accepted final stage (or sets status to accepted) and fires the usual Discord notification.

Returns: The updated Application object

POST /api/v1/applications/{id}/reject applications:write

Reject the application.

Parameter In Type Required Description
reason body string optional Optional rejection reason (max 1000 chars), included in the notification.

Returns: The updated Application object

POST /api/v1/applications/{id}/move applications:write

Move the application to a specific workflow stage.

Parameter In Type Required Description
stage_id body integer required Target workflow stage id. Must belong to the application's workflow.
notes body string optional Optional note (max 1000 chars).

Returns: The updated Application object

DELETE /api/v1/applications/{id} applications:write

Permanently delete the application and its uploaded files.

Returns: { "deleted": true }

In-Game Applicants

POST /api/v1/ingame/mail

Collect the queued phone notifications for the players a game server currently has online, and mark them delivered. Each one is handed over exactly once, so poll on a timer and deliver what comes back. Queued when an application is submitted and when it enters a stage with email notifications enabled.

Parameter In Type Required Description
discord_ids body string[] required Discord user ids of the players online (1–256, digits only).

Returns: { sender, mail: [{ id, discord_id, application_id, kind, subject, message, created_at }] }

GET /api/v1/ingame/applications

A player's own applications to this guild, newest first, with whether each can still be withdrawn. A Discord id with no Guildbase account returns an empty list rather than an error.

Parameter In Type Required Description
discord_id query string required Discord user id of the player (digits only).

Returns: { applications: [{ id, status, is_final, template, stage, submitted_at, can_withdraw }] }

POST /api/v1/ingame/applications/{id}/withdraw

The applicant withdrawing their own application. Only possible while it is submitted or in review, the same rule as the website. Recorded on the application's timeline.

Parameter In Type Required Description
discord_id body string required Discord user id of the player. Must own the application, or the response is 404.
reason body string optional Optional reason (max 1000 chars), shown to reviewers on the timeline.

Returns: { withdrawn: true, message }

In-Game Staff Review

GET /api/v1/staff/resolve staff:review

Identify a Discord user within this key's guild and report what they are allowed to do. Call it once per key to build a staff member's guild picker — a 403 not_staff simply means "no access here".

Parameter In Type Required Description
discord_id query string required Discord user id of the staff member (digits only).

Returns: { guild, staff, permissions, counts, templates }

GET /api/v1/staff/applications staff:review

List the applications this staff member may see. Templates they have no access to are excluded.

Parameter In Type Required Description
discord_id query string required Discord user id of the staff member.
status query string optional pending (submitted + in_review), submitted, in_review, accepted, rejected, withdrawn.
template_id query integer optional Filter by application template id.
risk_level query string optional low, medium, high, or flagged for anything above low.
claimed query boolean optional Only claimed (true) or unclaimed (false) applications.
search query string optional Match the applicant's username, Discord username, Discord id (a <@id> mention works) or the application id.
sort query string optional submitted_at (default), created_at or updated_at.
direction query string optional asc or desc (default).
page query integer optional Page number.
per_page query integer optional Items per page, 1–100.

Returns: Paginated list of Application objects

GET /api/v1/staff/applications/{id} staff:review

One application in full: answers, the stages it can move to, the last AI scan, the pushback reason, its timeline, and this staff member's permissions.

Parameter In Type Required Description
discord_id query string required Discord user id of the staff member.

Returns: { application, stages, ai_detection, latest_pushback, can_be_pushed_back, history, permissions }

POST /api/v1/staff/applications/{id}/approve staff:review

Approve the application. Needs the applications.review permission.

Parameter In Type Required Description
discord_id body string required Discord user id of the staff member.

Returns: { message, stage_action_warning, application }

POST /api/v1/staff/applications/{id}/reject staff:review

Reject the application. Needs applications.review.

Parameter In Type Required Description
discord_id body string required Discord user id of the staff member.
reason body string optional Rejection reason (max 1000 chars), included in the notification.

Returns: { message, stage_action_warning, application }

POST /api/v1/staff/applications/{id}/move staff:review

Move the application to a named stage. Needs applications.manage.

Parameter In Type Required Description
discord_id body string required Discord user id of the staff member.
stage_id body integer required Target stage id. Must belong to the application's workflow.
notes body string optional Optional note (max 1000 chars).

Returns: { message, stage_action_warning, application }

POST /api/v1/staff/applications/{id}/advance staff:review

Move to the next stage in the workflow without naming it. Needs applications.manage.

Parameter In Type Required Description
discord_id body string required Discord user id of the staff member.

Returns: { message, stage_action_warning, application }

POST /api/v1/staff/applications/{id}/pushback staff:review

Hand the application back to the applicant for revisions. Only possible from the initial stage. Needs applications.review.

Parameter In Type Required Description
discord_id body string required Discord user id of the staff member.
reason body string required What needs changing (10–1000 chars). Shown to the applicant.

Returns: { message, application }

POST /api/v1/staff/applications/{id}/overturn staff:review

Undo a final decision and return the application to review, reversing the final stage's actions (granted roles and so on). Needs applications.overturn.

Parameter In Type Required Description
discord_id body string required Discord user id of the staff member.
stage_id body integer required Active (non-final) stage to return it to.
reason body string required Why the decision is being overturned (max 1000 chars).

Returns: { message, application }

POST /api/v1/staff/applications/{id}/claim staff:review

Claim the application so the rest of the team can see it is being handled. Needs applications.review or applications.manage.

Parameter In Type Required Description
discord_id body string required Discord user id of the staff member.

Returns: { message, application }

POST /api/v1/staff/applications/{id}/unclaim staff:review

Release a claim. Only the holder or the guild owner may do this.

Parameter In Type Required Description
discord_id body string required Discord user id of the staff member.

Returns: { message, application }

POST /api/v1/staff/applications/{id}/ai-check staff:review

Run AI detection over the written answers — the same scan as the dashboard button, including the ai_generated flag and risk escalation. Pro only.

Parameter In Type Required Description
discord_id body string required Discord user id of the staff member.

Returns: { results, interpretation, message, application }

DELETE /api/v1/staff/applications/{id} staff:review

Permanently delete the application and its uploads. Needs applications.delete.

Parameter In Type Required Description
discord_id body string required Discord user id of the staff member.

Returns: { deleted: true, message }

Members

GET /api/v1/members members:read

List guild members.

Parameter In Type Required Description
role_id query integer optional Filter by role id.
page query integer optional Page number.
per_page query integer optional Items per page, 1–100.

Returns: Paginated list of GuildMember objects

GET /api/v1/members/{id} members:read

Retrieve a member.

Returns: A GuildMember object

POST /api/v1/members members:write

Add an existing Guildbase user to the guild.

Parameter In Type Required Description
user_id body integer conditional Guildbase user id. Required unless discord_id is given.
discord_id body string conditional Discord user id. Required unless user_id is given.
role_id body integer optional Role to assign. Must belong to the guild.

Returns: The created GuildMember object (201)

PATCH /api/v1/members/{id} members:write

Change a member's role.

Parameter In Type Required Description
role_id body integer|null required New role id, or null to clear the role. Field must be present.

Returns: The updated GuildMember object

DELETE /api/v1/members/{id} members:write

Remove a member from the guild.

Returns: { "deleted": true }

Roles

GET /api/v1/roles roles:read

List guild roles with their permissions.

Parameter In Type Required Description
page query integer optional Page number.
per_page query integer optional Items per page, 1–100.

Returns: Paginated list of GuildRole objects

GET /api/v1/roles/{id} roles:read

Retrieve a role.

Returns: A GuildRole object

POST /api/v1/roles roles:write

Create a custom role.

Parameter In Type Required Description
name body string required Role name (max 50).
color body string required Hex colour, e.g. #8b5cf6.
permissions body string[] optional Array of permission keys (validated against the guild permission list).
discord_role_id body string optional Discord role id to map (must be unique within the guild).

Returns: The created GuildRole object (201)

PATCH /api/v1/roles/{id} roles:write

Update a role. Default roles (e.g. Owner) are locked and return 422.

Parameter In Type Required Description
name body string optional Role name (max 50).
color body string optional Hex colour.
permissions body string[] optional Replaces the role's permission set.
discord_role_id body string optional Discord role mapping.

Returns: The updated GuildRole object

DELETE /api/v1/roles/{id} roles:write

Delete a role. Default roles are locked and return 422.

Returns: { "deleted": true }

Exams & Certificates

GET /api/v1/exams exams:read

List exam templates.

Parameter In Type Required Description
page query integer optional Page number.
per_page query integer optional Items per page, 1–100.

Returns: Paginated list of ExamTemplate objects

GET /api/v1/exams/{id} exams:read

Retrieve an exam template.

Returns: An ExamTemplate object

GET /api/v1/exams/{id}/attempts exams:read

List attempts for an exam.

Parameter In Type Required Description
status query string optional Filter by attempt status (in_progress, submitted, graded, ...).
page query integer optional Page number.
per_page query integer optional Items per page, 1–100.

Returns: Paginated list of ExamAttempt objects

GET /api/v1/attempts/{id} exams:read

Retrieve a single attempt.

Returns: An ExamAttempt object

GET /api/v1/certificates exams:read

List issued certificates.

Parameter In Type Required Description
exam_template_id query integer optional Filter by exam template.
user_id query integer optional Filter by recipient user id.
valid query boolean optional true = not revoked, false = revoked.
page query integer optional Page number.
per_page query integer optional Items per page, 1–100.

Returns: Paginated list of ExamCertificate objects

GET /api/v1/certificates/{id} exams:read

Retrieve a certificate.

Returns: An ExamCertificate object

POST /api/v1/certificates/{id}/revoke exams:write

Revoke a certificate.

Parameter In Type Required Description
reason body string optional Optional revocation reason (max 500).

Returns: The updated ExamCertificate object

Objects

The shape of every resource returned by the API. Nested objects (like user or current_stage) reference the types below.

Guild

The guild a key is scoped to.

Field Type Description
id integer Guild id.
name string Display name.
slug string URL slug.
description string|null Guild description.
is_pro boolean Whether the guild has Pro.
member_count integer Member count (present on GET /guild).
created_at string (ISO 8601) Creation timestamp.
{
  "success": true,
  "data": {
    "id": 42,
    "name": "Nightfall Syndicate",
    "slug": "nightfall",
    "description": "Competitive roleplay community.",
    "is_pro": true,
    "member_count": 318,
    "created_at": "2026-01-04T18:22:10+00:00"
  }
}

ApplicationTemplate

A form definition applicants submit against.

Field Type Description
id integer Template id.
name string Template name.
slug string URL slug.
description string|null Description shown to applicants.
status string Computed: draft, live, closed, scheduled or full.
is_active boolean Whether the template is enabled.
is_public boolean Whether it is listed publicly.
access_mode string Who may apply (e.g. everyone, roles).
allow_multiple_submissions boolean Whether a user may submit more than once.
opens_at string|null ISO 8601 open time, or null.
closes_at string|null ISO 8601 close time, or null.
applications_count integer Number of applications (on list/show).
workflow_id integer|null Workflow this template feeds.
created_at string (ISO 8601) Creation timestamp.
{
  "success": true,
  "data": {
    "id": 7,
    "name": "Police Whitelist",
    "slug": "police-whitelist",
    "description": "Apply to join the PD.",
    "status": "live",
    "is_active": true,
    "is_public": true,
    "access_mode": "everyone",
    "allow_multiple_submissions": false,
    "opens_at": null,
    "closes_at": null,
    "applications_count": 128,
    "workflow_id": 12,
    "created_at": "2026-03-11T09:00:00+00:00"
  }
}

Application

A submitted application. The answers array is only included on the single-application endpoint.

Field Type Description
id string (uuid) Application id.
guild_id integer Owning guild id.
status string pending, in_review, accepted, rejected or withdrawn.
is_final boolean Whether the application is in a terminal state.
risk_level string|null Automated risk assessment (low/medium/high).
flags string[] Automated flags raised on the application.
revision_count integer How many times it has been resubmitted.
time_spent_seconds integer|null Time the applicant spent completing the form.
submitted_at string|null ISO 8601 submission time.
created_at string (ISO 8601) Creation timestamp.
updated_at string (ISO 8601) Last update timestamp.
template ApplicationTemplate|omitted Included when loaded (see obj-template).
user UserSummary|omitted The applicant (see obj-user).
current_stage WorkflowStage|omitted Current workflow stage (see obj-stage).
workflow_id integer|null Workflow id.
is_claimed boolean Whether a reviewer has claimed it.
claimed_by UserSummary|omitted Reviewer who claimed it.
claimed_at string|null ISO 8601 claim time.
answers Section[]|omitted Formatted answers. Only on GET /applications/{id}.
{
  "success": true,
  "data": {
    "id": "9b1deae4-2f6a-4c1e-9a0b-2e5f7c3a11d2",
    "guild_id": 42,
    "status": "in_review",
    "is_final": false,
    "risk_level": "low",
    "flags": [],
    "revision_count": 0,
    "time_spent_seconds": 214,
    "submitted_at": "2026-07-20T14:05:00+00:00",
    "created_at": "2026-07-20T14:01:26+00:00",
    "updated_at": "2026-07-20T15:10:03+00:00",
    "template": { "id": 7, "name": "Police Whitelist", "slug": "police-whitelist", "status": "live" },
    "user": {
      "id": 8, "username": "ecliptor", "display_name": "Ecliptor",
      "avatar_url": "https://cdn.discordapp.com/avatars/12.../a.png", "discord_id": "123456789012345678"
    },
    "current_stage": { "id": 3, "name": "Interview", "color": "#8b5cf6", "position": 2, "is_final": false, "final_status": null },
    "workflow_id": 12,
    "is_claimed": true,
    "claimed_by": { "id": 2, "username": "hr_lead", "display_name": "HR Lead", "avatar_url": null, "discord_id": "98765..." },
    "claimed_at": "2026-07-20T14:40:00+00:00",
    "answers": [
      {
        "title": "About you",
        "fields": [
          { "label": "Age", "type": "number", "value": "24", "formatted_value": "24" },
          { "label": "Why join?", "type": "textarea", "value": "I love RP.", "formatted_value": "I love RP." }
        ]
      }
    ]
  }
}

GuildMember

A user's membership within a guild.

Field Type Description
id integer Membership id (used in member endpoints).
guild_id integer Guild id.
role GuildRole|null|omitted Assigned role (see obj-role).
user UserSummary|omitted The user (see obj-user).
joined_at string|null ISO 8601 join time.
{
  "success": true,
  "data": {
    "id": 501,
    "guild_id": 42,
    "role": { "id": 4, "name": "Moderator", "color": "#22c55e", "position": 5, "is_default": false },
    "user": { "id": 8, "username": "ecliptor", "display_name": "Ecliptor", "avatar_url": null, "discord_id": "1234..." },
    "joined_at": "2026-05-02T11:30:00+00:00"
  }
}

GuildRole

A permission role within a guild.

Field Type Description
id integer Role id.
name string Role name.
color string Hex colour.
position integer Sort position.
is_default boolean Default roles (e.g. Owner) are locked from edit/delete.
discord_role_id string|null Mapped Discord role id.
permissions string[]|omitted Permission keys (present on role endpoints).
members_count integer Members with this role (on list/show).
created_at string (ISO 8601) Creation timestamp.
{
  "success": true,
  "data": {
    "id": 4,
    "name": "Moderator",
    "color": "#22c55e",
    "position": 5,
    "is_default": false,
    "discord_role_id": "1102938475610293847",
    "permissions": ["applications.view", "applications.review", "tickets.view"],
    "members_count": 12,
    "created_at": "2026-02-18T20:15:00+00:00"
  }
}

ExamTemplate

An exam definition.

Field Type Description
id integer Exam id.
name string Exam name.
slug string URL slug.
description string|null Description.
is_active boolean Whether the exam is enabled.
access_mode string Who may take it.
time_limit_minutes integer|null Time limit, or null for none.
max_attempts integer|null Attempt cap per user.
pass_mark number|null Pass threshold (percent).
certificate_enabled boolean Whether passing issues a certificate.
published_at string|null ISO 8601 publish time.
opens_at string|null ISO 8601 open time.
closes_at string|null ISO 8601 close time.
sections_count integer Section count (on list/show).
questions_count integer Question count (on list/show).
attempts_count integer Attempt count (on list/show).
created_at string (ISO 8601) Creation timestamp.
{
  "success": true,
  "data": {
    "id": 15,
    "name": "Driving Theory",
    "slug": "driving-theory",
    "description": "Rules of the road.",
    "is_active": true,
    "access_mode": "roles",
    "time_limit_minutes": 30,
    "max_attempts": 2,
    "pass_mark": 80,
    "certificate_enabled": true,
    "published_at": "2026-06-01T00:00:00+00:00",
    "opens_at": null,
    "closes_at": null,
    "sections_count": 3,
    "questions_count": 40,
    "attempts_count": 210,
    "created_at": "2026-05-20T12:00:00+00:00"
  }
}

ExamAttempt

A single user's attempt at an exam.

Field Type Description
id integer Attempt id.
guild_id integer Guild id.
exam_template_id integer Exam id.
attempt_number integer Nth attempt for this user.
status string in_progress, submitted, graded, expired, etc.
score number|null Raw score.
max_score number|null Maximum possible score.
percent number|null Score as a percentage.
grade_label string|null Grade band label.
requires_manual_grading boolean Whether manual grading is pending.
violation_count integer Anti-cheat violations recorded.
risk_level string|null Risk assessment.
started_at string|null ISO 8601 start time.
submitted_at string|null ISO 8601 submit time.
released_at string|null ISO 8601 results-release time.
time_spent_seconds integer|null Time spent.
exam ExamTemplate|omitted Included on the single-attempt endpoint.
user UserSummary|omitted The candidate.
{
  "success": true,
  "data": {
    "id": 9032,
    "guild_id": 42,
    "exam_template_id": 15,
    "attempt_number": 1,
    "status": "graded",
    "score": 34,
    "max_score": 40,
    "percent": 85,
    "grade_label": "Pass",
    "requires_manual_grading": false,
    "violation_count": 0,
    "risk_level": "low",
    "started_at": "2026-07-19T10:00:00+00:00",
    "submitted_at": "2026-07-19T10:24:00+00:00",
    "released_at": "2026-07-19T10:24:05+00:00",
    "time_spent_seconds": 1440,
    "user": { "id": 8, "username": "ecliptor", "display_name": "Ecliptor", "avatar_url": null, "discord_id": "1234..." }
  }
}

ExamCertificate

A certificate issued for a passing attempt.

Field Type Description
id integer Certificate id.
code string Public verification code.
guild_id integer Guild id.
exam_template_id integer Exam id.
exam_attempt_id integer Source attempt id.
recipient_name string Name printed on the certificate.
exam_name string Exam name snapshot.
score_percent number|null Score achieved.
grade_label string|null Grade band.
is_valid boolean Not expired and not revoked.
is_revoked boolean Whether it has been revoked.
issued_at string|null ISO 8601 issue time.
expires_at string|null ISO 8601 expiry, or null.
revoked_at string|null ISO 8601 revocation time.
revoked_reason string|null Reason supplied at revocation.
user UserSummary|omitted The recipient.
{
  "success": true,
  "data": {
    "id": 771,
    "code": "GB-CERT-4F9A2C",
    "guild_id": 42,
    "exam_template_id": 15,
    "exam_attempt_id": 9032,
    "recipient_name": "Ecliptor",
    "exam_name": "Driving Theory",
    "score_percent": 85,
    "grade_label": "Pass",
    "is_valid": true,
    "is_revoked": false,
    "issued_at": "2026-07-19T10:24:05+00:00",
    "expires_at": "2027-07-19T10:24:05+00:00",
    "revoked_at": null,
    "revoked_reason": null,
    "user": { "id": 8, "username": "ecliptor", "display_name": "Ecliptor", "avatar_url": null, "discord_id": "1234..." }
  }
}

UserSummary

A minimal, PII-safe view of a user embedded in other objects.

Field Type Description
id integer User id.
username string Guildbase username.
display_name string|null Display name.
avatar_url string|null Avatar URL.
discord_id string|null Linked Discord user id.
{
  "id": 8,
  "username": "ecliptor",
  "display_name": "Ecliptor",
  "avatar_url": "https://cdn.discordapp.com/avatars/12.../a.png",
  "discord_id": "123456789012345678"
}

WorkflowStage

A stage within an application workflow.

Field Type Description
id integer Stage id.
name string Stage name.
color string|null Hex colour.
position integer Order within the workflow.
is_final boolean Whether this is a terminal stage.
final_status string|null accepted or rejected when is_final is true.
{
  "id": 3,
  "name": "Interview",
  "color": "#8b5cf6",
  "position": 2,
  "is_final": false,
  "final_status": null
}