api

KLYQ API Docs

Integrate influencer discovery and campaign creation directly into your platform.

Base URLhttps://api.klyqcollective.com/api/v1

Test URLhttps://backend-dev-b58f.up.railway.app/api/v1

1. Authentication

KLYQ uses two authentication mechanisms depending on the integration type.

Mechanism	Header	Purpose
JWT	Authorization: Bearer <token>	Brand dashboard login, key management
API Key	X-API-Key: klyq_test_xxx	External app-to-server integration

2. Marketplace Discovery

2.1 Get Paystack Config

bash

curl -X GET https://api.klyqcollective.com/api/v1/marketplace/paystack-config

200Response

json

{
  "public_key": "pk_test_abc123...",
  "test_mode": true,
  "enabled": true
}

Use public_key to initialize Paystack inline JS. If enabled: false, handle gracefully.

2.2 List Verified Influencers (Directory)

bash

curl -X GET "https://api.klyqcollective.com/api/v1/marketplace/directory?platform=instagram&location=Lagos&niche=fashion&min_rating=3&page=1&limit=10"

Query Parameters

Param	Type	Description
platform	string	twitter, instagram, tiktok, facebook
location	string	City/State (partial match)
niche	string	Niche (partial match)
gender	string	male, female
min_followers	int	Minimum follower count
max_followers	int	Maximum follower count
min_rating	float	Minimum 1-5 rating
page	int	Default 1
limit	int	Default 20, max 100
seed	string	Stable random shuffle seed

No prices are shown. Pricing only surfaces in cart (5+ influencers) or checkout.

2.3 AI Campaign Match

bash

curl -X POST https://api.klyqcollective.com/api/v1/marketplace/ai-match \
  -H "Content-Type: application/json" \
  -d '{
    "campaign_description": "Streetwear brand launching in Lagos...",
    "budget": 150000,
    "platforms": ["instagram", "tiktok"],
    "min_influencers": 10
  }'

Request Body

Field	Type	Required	Description
campaign_description	string	Yes	Free-text campaign description
budget	float	No	Max budget in Naira. Hard cap — count becomes a target.
platforms	[]string	No	Preferred platforms to prioritize
min_influencers	int	No	Target count (5 min if omitted). Strict only when no budget.

200Response

json

{
  "matches": [
    {
      "influencer_uid": "a1b2c3d4-...",
      "influencer_name": "Amara Styles",
      "platform": "instagram",
      "reason": "Lagos-based streetwear influencer with 15K engaged Gen Z followers on Instagram",
      "follower_count": 15000,
      "profile_image": "https://res.cloudinary.com/klyq/...",
      "niche": "fashion",
      "location": "Lagos"
    }
  ],
  "summary": "Selected 8 Lagos-based fashion and lifestyle influencers. 2 short of target due to budget constraints."
}

Budget too tight: {"message": "budget too tight: 10 influencers cost at least ₦250,000 but your budget is ₦150,000"}

Not enough matches: {"message": "AI could only match 3 influencers — checkout requires at least 5. Try a broader campaign description or increase budget."}

2.4 List Platforms

bash

curl -X GET https://api.klyqcollective.com/api/v1/marketplace/platforms

200

json

["twitter", "instagram", "tiktok", "facebook"]

3. Creating Campaigns (Checkout)

3.1 Via API Key (External Integration)

POST/api/v1/api/campaigns/create

Auth: X-API-Key

bash

curl -X POST https://api.klyqcollective.com/api/v1/api/campaigns/create \
  -H "X-API-Key: klyq_test_a1b2c3d4e5f6...a9b0" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Launch our new streetwear collection — casual fits, bold colors...",
    "callback_url": "https://your-frontend.com/success",
    "items": [
      {"influencer_uid": "a1b2c3d4-...", "platform": "instagram", "post_count": 1},
      {"influencer_uid": "b2c3d4e5-...", "platform": "instagram", "post_count": 1},
      {"influencer_uid": "c3d4e5f6-...", "platform": "tiktok", "post_count": 1},
      {"influencer_uid": "d4e5f6a7-...", "platform": "instagram", "post_count": 1},
      {"influencer_uid": "e5f6a7b8-...", "platform": "tiktok", "post_count": 1}
    ]
  }'

Request Body

Field	Type	Required	Description
brief	string	Yes	Campaign brief (objectives, creative direction)
callback_url	string	Yes	URL to redirect after payment (success/cancel)
items[].influencer_uid	string	Yes	Influencer UID from directory or AI match
items[].platform	string	Yes	twitter, instagram, tiktok, facebook
items[].post_count	int	Yes	Number of posts (min 1)

Minimum 5 unique influencers required.

200Response (Test key)

json

{
  "message": "proceed to payment",
  "campaign_uid": "camp-a1b2c3d4-...",
  "total_quote": 32500,
  "rate_applied": "30% partnership",
  "checkout_url": "https://checkout.bachs.io/c/chk_1a2b3c4d5e",
  "checkout_id": "chk_1a2b3c4d5e6f",
  "reference": "klyq_campa1b2_78901234"
}

Pricing Example (30% partnership):

Instagram 15K followers: Walk-in ₦25,000, ActualPay ₦10,000, KLYQ Cut ₦15,000
You Pay: ₦10,000 + (0.30 × 15,000) = ₦14,500

Errors

Code	Body
400	{"message": "select 5 at least"}
401	{"message": "invalid api key"}
404	{"message": "influencer not found"}

3.2 Via JWT (Brand Dashboard)

POST/api/v1/brand/checkout

Auth: Bearer <brand_jwt>

Same request/response format as 4.1, but uses Authorization: Bearer instead of X-API-Key. Does not include is_test in response.

4. Payment

4.1 Verify Payment

bash

curl -X GET https://api.klyqcollective.com/api/v1/brand/payments/klyq_campa1b2_78901234/verify \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

200Success

json

{
  "payment_status": "success",
  "amount_paid": 32500,
  "reference": "klyq_campa1b2_78901234"
}

On success, campaign auto-transitions to in_progress.

200Pending

json

{
  "payment_status": "pending",
  "amount_paid": 0,
  "reference": "klyq_campa1b2_78901234"
}

200Failed

json

{
  "payment_status": "failed",
  "amount_paid": 32500,
  "reference": "klyq_campa1b2_78901234"
}

5. Test Cards (Paystack Sandbox)

Scenario	Card Number
Success	4084 0840 8408 4081
Decline	4000 0000 0000 0002

CVV

Any 3 digits

Expiry

Any future date

OTP

123456

6. End-to-End Integration Flow

TEST MODE

bash

# 1. Generate test key (one-time)
TOKEN=$(curl -s -X POST https://api.klyqcollective.com/api/v1/auth/brand/login ... | jq -r .token)
TEST_KEY=$(curl -s -X POST https://api.klyqcollective.com/api/v1/brand/api-keys \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name":"Sandbox","key_env":"test"}' | jq -r .api_key)

# 2. Discover influencers
curl -s "https://api.klyqcollective.com/api/v1/marketplace/directory?platform=instagram&limit=50" \
  | jq '.influencers[].uid' > influencers.txt

# 3. Get AI recommendations
curl -s -X POST https://api.klyqcollective.com/api/v1/marketplace/ai-match \
  -H "Content-Type: application/json" \
  -d '{"campaign_description":"My campaign...","min_influencers":10}' \
  | jq '.matches[].influencer_uid' >> influencers.txt

# 4. Pick 5+ unique influencers, create campaign
curl -s -X POST https://api.klyqcollective.com/api/v1/api/campaigns/create \
  -H "X-API-Key: $TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "brief": "Testing integration flow",
    "callback_url": "https://your-frontend.com/success",
    "items": [
      {"influencer_uid":"uid1","platform":"instagram","post_count":1},
      {"influencer_uid":"uid2","platform":"instagram","post_count":1},
      {"influencer_uid":"uid3","platform":"tiktok","post_count":1},
      {"influencer_uid":"uid4","platform":"instagram","post_count":1},
      {"influencer_uid":"uid5","platform":"tiktok","post_count":1}
    ]
  }' > checkout.json

# 5. Extract payment URL and redirect user
CHECKOUT_URL=$(jq -r .checkout_url checkout.json)
CAMPAIGN_UID=$(jq -r .campaign_uid checkout.json)
echo "Send user to: $CHECKOUT_URL"

# 6. After payment, verify
curl -s "https://api.klyqcollective.com/api/v1/brand/payments/$(jq -r .reference checkout.json)/verify" \
  -H "Authorization: Bearer $TOKEN"

7. Campaign Lifecycle

pending

→

paymentspayment verified

→

in_progress

→

admin marks complete

→

completed

8. Error Format

All errors follow this shape:

json

{
  "code": 400,
  "message": "human-readable message",
  "logMsg": "internal detail (only in dev)"
}

Common status codes: 400 401 403 404 409 500

9. Rate Limits

publicPublic endpoints: 100 requests/minute per IP
keyAPI key endpoints: Shared IP-based limit (per-key limits coming soon)

Headers on all responses: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset