Core REST Endpoints

Explore the submissions, programs, and payouts endpoints with request/response samples.

12 min readUpdated Oct 11, 2025API Reference

Core REST Endpoints

The NidFul REST API provides comprehensive endpoints attuned to African program operations. All endpoints are namespaced under https://api.nidful.com/v1.

Authentication

Include a bearer token in every request:

Authorization: Bearer {access_token}

Submissions

List Submissions

GET /v1/submissions?programId=prog_123&state=open

Query Params

programId – Filter to a specific program.
state – open, resolved, or closed.
severity – critical, high, medium, low.

Response Snippet

{
  "data": [
    {
      "id": "sub_98231",
      "title": "IDOR in airtime transfer API",
      "severity": "high",
      "state": "triaged",
      "reported_at": "2025-09-24T12:04:22Z",
      "program": {
        "id": "prog_123",
        "name": "ExamplePay Bug Bounty"
      }
    }
  ]
}

Update Submission Status

PATCH /v1/submissions/sub_98231
{
  "state": "resolved",
  "resolution_summary": "Patched validation on transfer endpoint",
  "fixed_version": "2025.38.1"
}

Comments

POST /v1/submissions/sub_98231/comments
{
  "visibility": "public",
  "body": "Thanks for the detailed proof of concept. We are shipping a fix."
}

Use visibility: "internal" for team-only notes.

Programs

GET /v1/programs/prog_123

Returns policy text, scope, bounty table, and response SLAs.

Payouts

POST /v1/payouts
{
  "submissionId": "sub_98231",
  "amount": 750,
  "currency": "USD",
  "motivation": "Impact on financial transactions"
}

Multi-currency support

Provide currency codes accepted in your finance profile. NidFul automatically handles conversions when paying via local rails.

Analytics

GET /v1/analytics/programs/prog_123/summary?period=30d

Returns resolution times, bounty spend, and vulnerability categories for executive dashboards.

Pagination

Use standard link headers:

Link: <https://api.nidful.com/v1/submissions?page=2&perPage=50>; rel="next"

Error Format

{
  "error": {
    "code": "validation_error",
    "message": "State transition not allowed",
    "details": [
      {
        "field": "state",
        "message": "Cannot move from resolved to triaged"
      }
    ]
  }
}

Remember to pair these endpoints with Authentication & Scopes and stay within the limits outlined in Rate Limits & Error Handling.