Federation Members API¶

This API endpoint provides access to federation member data, returning membership records for athletes who are members of clubs affiliated to the federation. This endpoint requires authentication with federation admin access.

Endpoint URL: https://{federation-domain}/api/federation-members/

For example: https://saaf.opentrack.run/api/federation-members/

API Playground¶

The API uses Django REST Framework's browsable API interface, which provides an interactive playground when accessed via a web browser. The playground allows you to:

Filter members using interactive form controls
Search across member names
Order results by various fields
Test different pagination limits
View results in JSON or HTML format
Try different HTTP methods (GET, POST, etc.)

To access the playground, simply navigate to the API URL while logged in with federation admin credentials.

Response Fields¶

Each federation member record in the response contains the following fields:

Role Information¶

Field	Type	Description
`url`	URL	Link to this specific membership record
`person`	URL	Link to the person's detail endpoint
`role`	URL	Link to the role detail endpoint
`organisation`	String	The club/organisation where the person is a member
`role_type`	String	Type of role (see Role Types below)
`role_status`	String	Status of the role: `OK`, `AWAITING`, or `EXPIRED`
`identifier`	String	Athlete/member ID within the organisation
`bib`	String	Bib number assigned for the current season
`date_from`	Date	Start date of the membership/role
`date_to`	Date	End/expiry date of the membership
`ordering`	Integer	Display order for the role
`is_renewing`	Boolean	Indicates if the member intends to renew
`renewal_date`	Date	Date when the membership was last renewed
`payment_status`	String	Payment status: `PAID`, `UNPAID`, or `INVOICED`
`section`	String	House, College, or Department within the club
`notes`	String	Additional notes about the membership
`membership_category`	String	Category of membership
`renewal_fee`	Decimal	Fee amount for renewal
`superseded`	Boolean	Indicates if a later role record exists (historical record)

Person Information (Read-Only)¶

Field	Type	Description
`first_name`	String	Person's first name
`last_name`	String	Person's last name
`first_name_local`	String	First name in local script/language
`last_name_local`	String	Last name in local script/language
`gender`	String	Gender: `M` or `F`
`nationality_id`	String	Nationality identifier code
`age_group`	String	Age group text (e.g., "U20", "Senior")

Role Types¶

The role_type field can have the following values:

Value	Description
`MEMBER`	Standard member
`REGISTERED`	Registered athlete
`APPEARS_ON`	Appears on records
`COACH`	Coach
`TO`	Technical Official
`EMAIL_RECIPIENT`	Email recipient
`ADMIN`	Administrator
`TREASURER`	Treasurer

Additional official roles and team manager roles may also be available depending on federation configuration.

Filtering¶

You can filter the federation members list using the following query parameters:

Parameter	Type	Description	Example
`date_to`	Date	Filter by membership end date	`?date_to=2024-12-31`
`date_from`	Date	Filter by membership start date	`?date_from=2024-01-01`
`max_date_to`	Date	Filter by membership end date is less than or equal	`?max_date_to=2024-12-31`
`min_date_from`	Date	Filter by membership start date is greater than or equal	`?min_date_from=2024-01-01`
`identifier`	String	Filter by member ID/identifier	`?identifier=12345`
`role_type`	String	Filter by role type	`?role_type=MEMBER`
`role_status`	String	Filter by status (`OK`, `AWAITING`, `EXPIRED`)	`?role_status=OK`
`is_renewing`	Boolean	Filter by renewal intent (`true` or `false`)	`?is_renewing=true`

Filter Examples¶

Get all active members:

/api/federation-members/?role_status=OK

Get all coaches:

/api/federation-members/?role_type=COACH

Get members expiring before end of 2024:

/api/federation-members/?date_to__lte=2024-12-31

Get members who are renewing:

/api/federation-members/?is_renewing=true&role_status=OK

Searching¶

The API supports text search across member names using the search parameter:

Parameter	Description	Example
`search`	Search in first name, last name, and local name fields	`?search=smith`

The search looks across:

person__first_name
person__last_name
person__first_name_local
person__last_name_local

Search Example¶

Find all members with "john" in their name:

/api/federation-members/?search=john

Ordering¶

You can order the results using the ordering parameter. Prefix with - for descending order.

Field	Description
`person__first_name`	Order by first name
`person__last_name`	Order by last name
`date_to`	Order by membership end date
`date_from`	Order by membership start date
`renewal_date`	Order by renewal date (default)

Default ordering: -renewal_date (most recently renewed first)

Ordering Examples¶

Order by last name (A to Z):

/api/federation-members/?ordering=person__last_name

Order by last name (Z to A):

/api/federation-members/?ordering=-person__last_name

Order by membership expiry date (earliest first):

/api/federation-members/?ordering=date_to

Order by most recently renewed:

/api/federation-members/?ordering=-renewal_date

Pagination¶

The API uses limit/offset pagination to control the number of results returned.

Parameter	Type	Description	Default
`limit`	Integer	Number of records to return	50
`offset`	Integer	Starting position in the result set	0

Pagination Examples¶

Get the first 10 members:

/api/federation-members/?limit=10

Get members 21-30 (second page of 10):

/api/federation-members/?limit=10&offset=20

Get 100 members ordered by last name:

/api/federation-members/?limit=100&ordering=person__last_name

Response Structure¶

Paginated responses include:

{
  "count": 250,
  "next": "https://saaf.opentrack.run/api/federation-members/?limit=50&offset=50",
  "previous": null,
  "results": [
    {
      "url": "https://saaf.opentrack.run/api/federation-members/12345/",
      "first_name": "John",
      "last_name": "Doe",
      ...
    }
  ]
}

count: Total number of results available
next: URL for the next page (null if on last page)
previous: URL for the previous page (null if on first page)
results: Array of member records for the current page

Combined Query Example¶

Get the first 20 active members (role_status=OK), ordered by last name, whose memberships don't expire before 2024:

/api/federation-members/?role_status=OK&date_to__gte=2024-01-01&ordering=person__last_name&limit=20

Permissions¶

To access this API, you must:

Be authenticated (logged in)
Have an admin role in the federation OR be a superuser
Access the API via the federation's domain (e.g., saaf.opentrack.run)

Notes¶

The API only returns members of clubs that are affiliated to the current federation
Only roles with role_type="MEMBER" and active persons (is_inactive=False) are included
Historical/superseded roles are included but marked with superseded: true
The playground interface is only available when accessing via a web browser with proper authentication