Configuration and Event Import API Specifications

Overview

The Event Import API allows users to create and update event filters with complex criteria. Once a configuration is saved, users can retrieve events matching the saved conditions through a dedicated export URL.

API Endpoint

Method: POST
Endpoint: http://api.yodel.today/users/e/filters/save
Content-Type: application/json

Authentication

This API requires authentication using a JWT token. The token must be included in the request headers.

Header: auth-token
Value: JWT token string

Example Authentication Header

auth-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2IxNjgzLCJpYXQiOjE3NDg0NTEzNTR9MvpwElTySO21d61x1vIdnJMKeEQnzSnJmUiglKHscQ

Complete cURL Example

curl --location 'http://api.yodel.today/users/e/filters/save' \
--header 'auth-token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX2IxNjgzLCJpYXQiOjE3NDg0NTEzNTR9MvpwElTySO21d61x1vIdnJMKeEQnzSnJmUiglKHscQ' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": null,
    "meta": {
        "name": "[e-mail]"
    },
    "filter": {
        "radius": {
            "address": "24449 Willowbrook Drive, Novi, MI, USA",
            "radius": "10"
        }
    }
}'

Request Structure

Required Parameters

Parameter	Type	Required	Description
meta	Object	Yes	Metadata for the filter
meta.name	String	Yes	Name of the filter (1-255 characters)
filter	Object	Yes	Filter criteria object

Optional Parameters

Parameter	Type	Required	Description
id	String/null	No	Id for updating existing filter, null for creating new

Configuration Criteria

The configuration object supports the following criteria and can be structured in two ways:

1. Root-Level Criteria

Direct filter criteria at the root level of the configuration object.

2. OR Conditions

Using the $or operator to specify multiple alternative conditions (maximum 5 conditions).

Note: You cannot mix root-level criteria with $or conditions in the same filter.

Available Configuration Criteria

Criterion	Type	Format	Description	Example
zip	String	ZIP code format	ZIP code filter (5 digits or 5+4 format)	"48375", "48375-1234"
radius	Object	Address + radius object	Geographic radius search	See radius object below
category	Number/String	Positive integer or numeric string	Event category filter	See category table below
keyword_strict	String	1-255 characters	Strict keyword matching	"concert"

Radius Object Structure

{
  "address": "702 W Kalamazoo St, Lansing, MI 48915",
  "radius": 10
}

Field	Type	Required	Description	Constraints
address	String	Yes	Full address for center point	5-500 characters
radius	Number	Yes	Radius in miles	Positive number, max 20

Request Examples

Example 1: Simple State and ZIP Configuration

{
  "id": null,
  "meta": {
    "name": "Michigan Events Filter"
  },
  "filter": {
    "zip": "48375"
  }
}

Example 2: OR Conditions with Multiple ZIP Codes

{
  "id": null,
  "meta": {
    "name": "Multi-ZIP Filter"
  },
  "filter": {
    "$or": [
      {"zip": "48375"},
      {"zip": "48376"},
    ]
  }
}

Example 3: Complex Configuration with Radius and Category

{
  "id": null,
  "meta": {
    "name": "Novi Area Music Events"
  },
  "filter": {
    "radius": {
      "address": "702 W Kalamazoo St, Lansing, MI 48915",
      "radius": 10
    },
        "$or": [
      {"category": "23"},
      {"category": "6"},
    ]
  }
}

Example 4: Mixed OR Conditions (from test file)

{
  "id": null,
  "meta": {
    "name": "[e-mail]"
  },
  "filter": {
    "$or": [
      {
        "zip": "48375"
      },
      {
        "zip": "48376"
      }
    ]
  }
}

Example 5: Updating an Existing Configuration

Original Configuration (created with previous request):

{
  "id": null,
  "meta": {
    "name": "Michigan Music Events"
  },
  "filter": {
    "category": 23
  }
}

Response from creation:

{
  "success": true,
  "id": "66d0abb6ac8f7fbea29207b4"
}

Update Request (using the returned id):

{
  "id": "66d0abb6ac8f7fbea29207b4",
  "meta": {
    "name": "Updated Michigan Music Events with Radius"
  },
  "filter": {
    "radius": {
      "address": "702 W Kalamazoo St, Lansing, MI 48915",
      "radius": 15
    },
    "category": 23,
    "keyword_strict": "concert"
  }
}

Update Response:

{
  "success": true,
  "id": "66d0abb6ac8f7fbea29207b4"
}

Note: When updating an existing filter: - The same id is returned in the response - All filter criteria are completely replaced (not merged) with the new criteria

Response Structure

Success Response

{
  "success": true,
  "id": "66d0abb6ac8f7fbea29207b4"
}

Field	Type	Description
success	Boolean	Indicates successful operation
id	String	MongoDB ObjectId of the saved filter

Error Response

{
  "success": false,
  "error": "Input validation failed",
  "message": "The provided input does not meet the required validation criteria",
  "details": [
    "meta.name: Meta name is required",
    "filter.state: State must be a 2-character state code (e.g., \"MI\", \"CA\")"
  ],
  "validationErrors": [...]
}

Field	Type	Description
success	Boolean	Always false for errors
error	String	Error type
message	String	Human-readable error message
details	Array	Detailed validation error messages
validationErrors	Array	Raw validation error objects

Validation Rules

General Rules

• At least one configuration criterion must be provided
• Cannot combine root-level criteria with $or conditions
• Maximum 5 conditions in $or array
• Maximum 5 ZIP code conditions in $or array

Field-Specific Validation

Meta Object

• name: Required, 1-255 characters

ZIP Code

• Must match pattern: 5 digits or 5+4 format
• Examples: "48375", "48375-1234"
• Max of 5 zip codes per API configuration

Radius

• address: Required, 5-500 characters
• radius: Required, positive number, maximum 20

Category

• Must be positive integer or numeric string
• Examples: 23, "23"

Keyword Strict

• 1-255 characters when provided

Using Saved Configurations

After successfully saving a configuration, you can retrieve events matching the saved conditions using the export URL:

Export URL Format:

https://my.yodel.today/api/v3/export/widget/json_v1/{id}

Example:

https://my.yodel.today/api/v3/export/widget/json_v1/66d0abb6ac8f7fbea29207b4

This URL will return events in JSON format that match the criteria defined in the saved filter.

HTTP Status Codes

Status Code	Description
200	Success - Filter saved successfully
400	Bad Request - Validation errors in request
500	Internal Server Error - Server-side error during save operation

Sample CURL

curl --location 'http://api-stage.yodel.today/events/e/filters/save' \
  --header 'auth-token: 1111222333' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "id": null,
    "meta": {
      "name": " [e-mail]"
    },
    "filter": {
      "state": "MI",
      "zip": "48375",
      "radius": {
        "address": "24449 Willowbrook Drive, Novi, MI, USA",
        "radius": "10"
      },
      "category": 23,
      "keyword_strict": "test1"
    }
  }'

Category Details:

• Standard Categories: Events categories are assigned by event owners within the Yodel program, specified categories from event sources, and AI analyzation.

Category Title	Static category_id
Business	1
Causes	4
Clubs	2
History & Museums	10
Health & Fitness	13
Lifestyle	18
Film	12
Religious	5
Hobbies	17
Auto, Boat & Air	9
Travel	26
Fashion	11
Sports, Youth	7
Arts	23
Science & Tech	24
Seasonal	25
Government	15
School	6
Food & Drink	14
Kids & Family	19
Parks & Rec	22
Music & Entertainment	8
Sports, Adult	27
Retail	28
Classes/Workshops	29
Festivals/Fairs	30
Markets	31
Outdoors	32