Integrations & API Reference¶

Overview¶

Nigall exposes two primary API surfaces: Mobile API (/api/mobile/v1/) for attendee JWT clients and Talent API (/api/v1/) for account-scoped CRM resources. Webhooks integrate Stripe and SES.

Purpose¶

Enable mobile apps, talent CRM integrations, and payment/email automation.

Who should use it¶

Mobile developers
Integration engineers
Partners building talent workflows

Benefits¶

RESTful JSON endpoints
JWT authentication for mobile
UUID-scoped talent resources
Documented webhook entry points

API	Base URL
Mobile	`/api/mobile/v1/`
Talent CRM	`/api/v1/`
Stripe webhook	`/payments/webhook/`
SES webhook	`/communications/webhooks/ses/`

Prerequisites¶

HTTPS in production
JWT secret configured for mobile
Account UUID for talent API calls
Webhook signing secrets

Mobile API (`mobile_api`)¶

Authentication¶

Method	Path	Body
POST	`/auth/login/`	username/email + password
GET	`/auth/me/`	Header: `Authorization: Bearer <token>`

Events¶

Method	Path	Description
GET	`/events/discover/`	Public discover list
GET	`/events/search/`	Search query
GET	`/events/categories/`	Category list
GET	`/events/<pk>/<event_tag>/`	Event detail
POST	`/events/<pk>/<event_tag>/rsvp/`	RSVP create/update (RSVP events)

Tickets¶

Method	Path	Description
GET	`/tickets/`	Authenticated user's tickets

Note: Survey questions not exposed on mobile RSVP. Full registration remains web.

Talent API (`talent_management.api`)¶

Account-scoped pattern:

/api/v1/accounts/<account_uuid>/<resource>/

Resource	Methods
`accounts/`	GET list, GET detail
`categories/`	CRUD
`talents/`	CRUD
`contacts/`	CRUD
`vip-guests/`	CRUD
`vip-registrations/`	CRUD
`programs/`	CRUD
`contracts/`	CRUD

ViewSets: talent_management.api.views

Webhooks¶

Stripe (`POST /payments/webhook/`)¶

Handles checkout completion, subscription payments, ticket fulfillment. Verify signature with Stripe webhook secret.

SES (`POST /communications/webhooks/ses/`)¶

Email bounce and complaint notifications.

Field descriptions¶

Header	Value
Authorization	`Bearer <jwt>` (mobile)
Content-Type	`application/json`

Business rules¶

Rule	Detail
Mobile RSVP	RSVP-type events only
Private events	Mobile detail enforces host check
Talent scoping	All resources under account UUID
No public write API	Event CRUD web-only

Validation rules¶

404 on pk/tag mismatch
401 without valid JWT

User permissions¶

API enforces same business rules as web views server-side.

Workflow¶

flowchart LR Mobile[Mobile app] --> JWT[JWT auth] JWT --> MobileAPI[/api/mobile/v1/] Integration[Partner] --> TalentAPI[/api/v1/accounts/.../] Stripe[Stripe] --> Webhook[/payments/webhook/]

Examples¶

Mobile login + tickets:

POST /api/mobile/v1/auth/login/
Content-Type: application/json

{"username": "user@example.com", "password": "..."}

List talents:

GET /api/v1/accounts/<uuid>/talents/
Authorization: Bearer <token>

Best practices¶

Store JWT securely (Keychain/Keystore)
Handle 401 with re-auth flow
Idempotent webhook handlers

Tips¶

Use events/categories/ for mobile filters
Talent UUIDs everywhere — not integer PKs

Common mistakes¶

Mistake	Result	Fix
Wrong account UUID	404	GET `/api/v1/accounts/`
RSVP on registration event	4xx	Use web registration

FAQs¶

GraphQL?
Not available — REST only.

API keys for organizers?
Not implemented — session auth on web.

Troubleshooting¶

Symptom	Cause	Fix
403 talent	User not linked to account	Link CustomUser.account
Webhook 400	Signature mismatch	Rotate secret

Screenshot placeholders¶

N/A — API documentation.

Administrator notes¶

Rate limit and monitor /auth/login/
Document webhook URLs in Stripe dashboard

Developer/API notes¶

App	Package
mobile_api	`mobile_api/views.py`, `urls.py`
talent API	`talent_management/api/`
Web auth	django-allauth session cookies

See also: Known Limitations