Create Survey Links API

Prerequisites

To use the APIs, you need to have a token. Tokens can be generated by an admin at the setting section in Filum CX platform. Ensure you have the necessary permissions to access the admin settings for token generation.

APIs

Access the APIs via the endpoint: https://api.filum.ai/

POST /external/survey-campaigns/{survey_campaign_id}/links

Summary

Create a survey link for a survey campaign.

This endpoint is idempotent: if you send the same request (same survey_campaign_id and metadata_mapping) multiple times, you will receive the same survey link. Duplicate requests do not create additional links.

Path Parameters

Name	Description	Required	Schema
survey_campaign_id	The unique identifier of the survey campaign	Yes	string (uuid)

Header Parameters

Name	Description	Required	Schema
authorization	The authorization token to validate the request. The value should be in the format Bearer <your_api_token>	Yes	string
organization-id	The unique identifier of your organization	Yes	string
auth-type	The type of authorization used for the request. In this case, the value should be token	Yes	string
content-type	The content type of the request body. The value should be application/json	Yes	string

Request Body

Field	Type	Required	Description
name	string	Yes	Display name for the survey link (1–255 characters, whitespace trimmed)
metadata_mapping	array of MetadataAssociation	No	List of metadata id–value pairs (e.g., business code). Max 200 items

MetadataAssociation object:

Field	Type	Required	Description
metadata_id	integer	Yes	The ID of the metadata field
value	string | number | array | null	No	The value for the metadata (string max 2000 chars, or float, or list, or null)

Request body sample:

{
  "name": "SKU 12345 - Link 001",
  "metadata_mapping": [
    {
      "metadata_id": 123,
      "value": "SKU-12345"
    },
    {
      "metadata_id": 456,
      "value": "2024-01-15"
    }
  ]
}

Responses

Code	Description	Content type
200	Successful Response	application/json
401	Unauthorized	application/json
403	Forbidden	application/json
404	Not Found	application/json
422	Validation Error	application/json
429	Too Many Requests	application/json

200 Successful Response

Returns the created (or existing) survey link.

Field	Type	Description
id	integer	The unique identifier of the survey link
public_id	string	Public identifier for the survey link
name	string	Display name of the survey link
metadata_mapping	array of MetadataMappingItem	Metadata id–value pairs with metadata details
created	string (ISO 8601 datetime)	Timestamp when the link was created
updated	string (ISO 8601 datetime)	Timestamp when the link was last updated

MetadataMappingItem object:

Field	Type	Description
metadata	object	Metadata details: id, name, variable
value	string | number | array | null	The value for the metadata

Response sample:

{
  "id": 12345,
  "public_id": "a1b2c3d4e5",
  "name": "SKU 12345 - Link 001",
  "metadata_mapping": [
    {
      "metadata": {
        "id": 123,
        "name": "SKU Number",
        "variable": "SKU Number"
      },
      "value": "SKU-12345"
    }
  ],
  "created": "2024-01-15T10:30:00Z",
  "updated": "2024-01-15T10:30:00Z"
}

Idempotency

This API is designed to be idempotent based on the combination of survey_campaign_id and metadata_mapping:

• If you call the API with the same survey_campaign_id and metadata_mapping values, you will receive the same survey link (the existing one).
• This prevents duplicate links from being created for the same business entity (e.g., SKU number).
• The name field is not part of the idempotency key, so changing only the name will still return the existing link.

Quota

Each survey campaign has a maximum limit on the number of survey links that can be created. If you exceed this limit, you will receive a 422 Validation Error response.

The default limit is 50 links per campaign, but this may be configured differently for your organization.

Rate Limiting

The API endpoint is rate-limited to ensure fair usage and system stability. The default rate limits are:

• Per second: 5 requests
• Per minute: 50 requests

If you exceed these limits, you will receive a 429 Too Many Requests response. Please implement appropriate retry logic with exponential backoff in your integration.

Error Responses

401 Unauthorized

{
  "detail": "Invalid or missing token"
}

403 Forbidden

{
  "detail": "Permission denied"
}

404 Not Found

{
  "detail": {
    "message": "not_found",
    "params": {
      "model": "survey_campaign"
    }
  }
}

422 Validation Error

Quota exceeded:

{
  "detail": {
    "message": "threshold_exceeded",
    "params": {
      "model": "survey_link",
      "threshold": 50
    }
  }
}

Invalid request body:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

429 Too Many Requests

{
  "detail": "Rate limit exceeded"
}