Search opportunities

This endpoint allows for the efficient searching and filtering of opportunity role records based on specified query parameters such as title, description, category, status, and created date. It is designed to support operations that require accessing detailed opportunity role information quickly and effectively.

Endpoint and Usage: Endpoint: GET /api/opportunities/search/ Base URL: https://api.vomevolunteer.com

Query Parameters:

Core Filters

• id (uuid): Filters opportunity roles by ID.

• title (string): Filters opportunity roles by title.

• description (string): Filters opportunity roles by description.

• status (string): Filters opportunity roles by status.

• created_at (string, ISO-8601): Filters opportunity roles by exact created_at.

• created_at.gt (string, ISO-8601): Filters by created_at > value.

• created_at.gte (string, ISO-8601): Filters by created_at >= value.

• created_at.lte (string, ISO-8601): Filters by created_at <= value.

• created_at.lt (string, ISO-8601): Filters by created_at < value.

• ordering (string): Sorts results by created_at or -created_at.

Opportunity Statuses

• 0: Draft

• 1: Published

• 2: Unpublished

Sample Requests

# id
GET /api/opportunities/search/?id=2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1

# title
GET /api/opportunities/search/?title=mentor

# description
GET /api/opportunities/search/?description=weekend

# status
GET /api/opportunities/search/?status=1

# created_at
GET /api/opportunities/search/?created_at=2024-09-06T02:57:15.008656Z

# created_at.gt
GET /api/opportunities/search/?created_at.gt=2024-09-06T02:57:15.008656Z

# created_at.gte
GET /api/opportunities/search/?created_at.gte=2024-09-06T02:57:15.008656Z

# created_at.lt
GET /api/opportunities/search/?created_at.lt=2024-09-06T02:57:15.008656Z

# created_at.lte
GET /api/opportunities/search/?created_at.lte=2024-09-06T02:57:15.008656Z

# ordering ascending
GET /api/opportunities/search/?ordering=created_at

# ordering descending
GET /api/opportunities/search/?ordering=-created_at

Category Filters Search by related category fields:

• category.id (uuid): Filters opportunity roles by the related category ID.

• category_id (uuid): Alias for category.id.

• category.title (string): Filters opportunity roles by the related category title.

• category_title (string): Alias for category.title.

Sample Requests

# category id
GET /api/opportunities/search/?category.id=d610ab31-e480-4ef1-9e35-94f94ebacde9

# category_id alias
GET /api/opportunities/search/?category_id=d610ab31-e480-4ef1-9e35-94f94ebacde9

# category title
GET /api/opportunities/search/?category.title=Community Outreach

# category_title alias
GET /api/opportunities/search/?category_title=Community Outreach

Authorization: Requests to this endpoint require an API-KEY in the header for authentication.

headers = {
    "API-KEY": "your_unique_api_key_here"
}

response = requests.get(
    "https://api.vomevolunteer.com/api/opportunities/search/?title=mentor&status=1",
    headers=headers
)

Response Structure: The response from this endpoint returns a paginated list of opportunities that match the query parameters, including details about each role’s related category and public share URL.

Example Response Object:

{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1",
      "created_at": "2026-02-05T07:40:29.324645Z",
      "category": {
        "id": "d610ab31-e480-4ef1-9e35-94f94ebacde9",
        "title": "Community Outreach",
        "description": "Programs and roles related to outreach work."
      },
      "title": "Weekend Mentor",
      "description": "Support volunteers during weekend sessions.",
      "share_opportunity_url": "https://www.vomevolunteer.com/opportunity-board/test%20organization/weekend%20mentor/2f56f3ef-08f5-4e5a-bf5b-76ca8fc4d5f1"
    }
  ]
}

Example Response Structure

Summary Information

• count: Total number of matching opportunity roles.

• next: URL for the next page of results, or null.

• previous: URL for the previous page of results, or null.

Opportunity Role Object

• id: Unique ID of the opportunity role.

• category: Related category information.

• category.id: Unique ID of the category.

• category.title: Title of the category.

• category.description: Description of the category.

• title: Title of the opportunity.

• description: Description of the opportunity.

• share_opportunity_url: Public share URL for the opportunity. This may be null if the role is not published.