{ "openapi": "3.1.0", "info": { "title": "ICON affiliate API", "version": "2026-09-28", "description": "Search offers for a lead, poll the results, submit the result the consumer chose; optionally pre-check duplicates. Every answer carries status, reason and code.\n\nDocumentation: https://developers.iconroute.io/" }, "servers": [ { "url": "https://iconroute.io" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Affiliate API" }, { "name": "Lead submission" } ], "paths": { "/api/v1/engine/search": { "post": { "tags": [ "Affiliate API" ], "summary": "Search offers for a lead", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "icon_campaign_id", "icon_affiliate_id", "lead", "tracking" ], "properties": { "icon_campaign_id": { "type": "string", "description": "ICON campaign ID (UUID) of the campaign this request is for. Required on every search and every submit: ICON never picks a campaign for you." }, "icon_affiliate_id": { "type": "string", "description": "Your ICON affiliate ID (UUID). Required on every search and every submit, and must be the affiliate your API key belongs to. ICON records the affiliate from the key; this value is only checked against it." }, "lead": { "$ref": "#/components/schemas/Lead" }, "tracking": { "allOf": [ { "$ref": "#/components/schemas/Tracking" } ], "required": [ "ip_address" ] }, "tcpa_consent": { "type": "boolean", "description": "The consumer's consent decision (see the Consent and TCPA page)." }, "icon_is_test_lead": { "type": "boolean", "description": "Test mode: held before any buyer receives it (TEST_LEAD_HELD)." } }, "additionalProperties": true }, "example": { "icon_campaign_id": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "icon_affiliate_id": "3c9d8e7f-1a2b-4c3d-9e8f-7a6b5c4d3e2f", "lead": { "personal": { "first_name": "Ada", "last_name": "Lovelace", "email": "ada.lovelace@mail.test", "phone": "6025552368", "date_of_birth": "1990-04-07" }, "address": { "address_line_1": "123 N Main St", "city": "Phoenix", "state": "AZ", "zip_code": "85004" }, "education": { "education_level": "bachelors", "high_school_graduation_year": "2008", "start_timeline": "1_3_months", "learning_preference": "online" }, "background": { "military_affiliation": "none", "us_citizen": "yes" } }, "tracking": { "ip_address": "203.0.113.9", "subid": "pub-42", "subid2": "creative-7", "utm_source": "partner", "utm_medium": "email", "utm_campaign": "fall-enrollment" }, "tcpa_consent": true, "trusted_form_cert_url": "https://cert.trustedform.com/0123456789abcdef0123456789abcdef01234567" } } } }, "responses": { "200": { "description": "OK: the search id and the first results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultsEnvelope" }, "example": { "code": "OK", "status": "accepted", "reason": "OK", "success": true, "icon_lead_id": "1e8d30bb-7c5f-41b9-8cf1-5e6b57abe999", "processing_done": false, "poll_after_ms": 1000, "accepted_count": 0, "max_accepted_submissions": 3, "true_exclusive_accepted": false, "offers": [ { "icon_result_id": "api-0b7e4a2c-981234", "campaign_id": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "offer": { "id": "0b7e4a2c-9d8f-4e1a-b2c3-d4e5f6a7b8c9", "name": "Example University", "offer_type": "shared", "is_exclusive": false, "tcpa_text": "By clicking Submit, I agree…" }, "school": { "name": "Example University", "logo_url": "https://cdn.example.com/logo.png" }, "programs": [ { "value": "4411", "label": "BS Business (Online)", "payout": 28 } ], "payout": 28, "form_fields": [ { "name": "api_field_military", "label": "Military affiliation", "type": "select", "required": true, "options": [ { "value": "none", "label": "None" } ] }, { "name": "api_field_rn_license", "label": "RN license?", "type": "select", "required": false, "required_when": { "program_ids": [ "4411" ] } } ], "expires_at": "2026-09-25T20:15:00Z" } ] } } } }, "400": { "description": "REQUIRED_FIELD_MISSING / INVALID_FIELD (the field is named), or NOT_FOUND: the campaign is not active or not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "401": { "description": "AUTH_REQUIRED (no API key) or AUTH_INVALID (a key ICON does not know); status invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "403": { "description": "FORBIDDEN: icon_affiliate_id is not the affiliate of your key, or the lead was already submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "429": { "description": "RATE_LIMITED (retryable): this API key is over its rate limit. Wait the Retry-After header's seconds (also retry_after_seconds) and retry. Limits are per API key and per leg: search 60 per minute with bursts of up to 10, results polling 600 per minute, submit 120 per minute, unless ICON set other limits for your key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "500": { "description": "INTERNAL_ERROR: not retryable as is; tell your ICON contact the time and the icon_lead_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "503": { "description": "UNAVAILABLE: retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } } } } }, "/api/v1/engine/results/{icon_lead_id}": { "get": { "tags": [ "Affiliate API" ], "summary": "Poll the results of a search", "parameters": [ { "name": "icon_lead_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "OK: every result so far.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultsEnvelope" }, "example": { "code": "OK", "status": "accepted", "reason": "OK", "success": true, "icon_lead_id": "1e8d30bb-7c5f-41b9-8cf1-5e6b57abe999", "processing_done": true, "accepted_count": 0, "max_accepted_submissions": 3, "true_exclusive_accepted": false, "offers": [ { "icon_result_id": "api-0b7e4a2c-981234", "campaign_id": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "offer": { "id": "0b7e4a2c-9d8f-4e1a-b2c3-d4e5f6a7b8c9", "name": "Example University", "offer_type": "shared", "is_exclusive": false, "tcpa_text": "By clicking Submit, I agree…" }, "school": { "name": "Example University", "logo_url": "https://cdn.example.com/logo.png" }, "programs": [ { "value": "4411", "label": "BS Business (Online)", "payout": 28 } ], "payout": 28, "form_fields": [ { "name": "api_field_military", "label": "Military affiliation", "type": "select", "required": true, "options": [ { "value": "none", "label": "None" } ] }, { "name": "api_field_rn_license", "label": "RN license?", "type": "select", "required": false, "required_when": { "program_ids": [ "4411" ] } } ], "expires_at": "2026-09-25T20:15:00Z" } ] } } } }, "401": { "description": "AUTH_REQUIRED (no API key) or AUTH_INVALID (a key ICON does not know); status invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "403": { "description": "FORBIDDEN: the campaign or offer is not yours.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "404": { "description": "NOT_FOUND: no search with that id belongs to your key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "429": { "description": "RATE_LIMITED (retryable): this API key is over its rate limit. Wait the Retry-After header's seconds (also retry_after_seconds) and retry. Limits are per API key and per leg: search 60 per minute with bursts of up to 10, results polling 600 per minute, submit 120 per minute, unless ICON set other limits for your key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "500": { "description": "INTERNAL_ERROR: not retryable as is; tell your ICON contact the time and the icon_lead_id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "503": { "description": "UNAVAILABLE: retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } } } } }, "/api/v1/engine/leads": { "post": { "tags": [ "Lead submission" ], "summary": "Submit a result, or post a lead to an offer", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "icon_campaign_id", "icon_affiliate_id" ], "anyOf": [ { "required": [ "icon_result_id" ] }, { "required": [ "icon_offer_id", "lead", "tracking" ] } ], "properties": { "icon_campaign_id": { "type": "string", "description": "ICON campaign ID (UUID) of the campaign this request is for. Required on every search and every submit: ICON never picks a campaign for you." }, "icon_affiliate_id": { "type": "string", "description": "Your ICON affiliate ID (UUID). Required on every search and every submit, and must be the affiliate your API key belongs to. ICON records the affiliate from the key; this value is only checked against it." }, "icon_offer_id": { "type": "string", "description": "The ICON offer id (UUID). Required when you post a lead straight to an offer; taken from the result when you submit an icon_result_id." }, "icon_lead_id": { "type": "string", "description": "The icon_lead_id ICON returned for a lead you posted directly: send it when you retry that post, so ICON recognises the lead. A request that would change a submitted lead is refused (403). Not used on a result submit (send search_lead_id)." }, "icon_result_id": { "type": "string", "description": "The result to submit (from search/results). With it, icon_offer_id is taken from the result." }, "search_lead_id": { "type": "string", "format": "uuid", "description": "The icon_lead_id of the search the result came from." }, "program_id": { "type": "string", "description": "The chosen program (a programs[].value of the result)." }, "icon_is_test_lead": { "type": "boolean", "description": "Test mode: held before any buyer receives it (TEST_LEAD_HELD)." }, "lead": { "$ref": "#/components/schemas/Lead" }, "tracking": { "$ref": "#/components/schemas/Tracking" }, "tcpa_consent": { "type": "boolean", "description": "The consumer's consent decision (see the Consent and TCPA page)." } }, "additionalProperties": true }, "examples": { "result": { "summary": "Submit a search result", "value": { "icon_result_id": "api-0b7e4a2c-981234", "search_lead_id": "1e8d30bb-7c5f-41b9-8cf1-5e6b57abe999", "icon_campaign_id": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "icon_affiliate_id": "3c9d8e7f-1a2b-4c3d-9e8f-7a6b5c4d3e2f", "program_id": "4411", "api_field_military": "none", "tcpa_consent": true, "consent_button_label": "Request information" } }, "direct": { "summary": "Post a lead to an offer", "value": { "icon_campaign_id": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "icon_affiliate_id": "3c9d8e7f-1a2b-4c3d-9e8f-7a6b5c4d3e2f", "icon_offer_id": "0b7e4a2c-9d8f-4e1a-b2c3-d4e5f6a7b8c9", "lead": { "personal": { "first_name": "Ada", "last_name": "Lovelace", "email": "ada.lovelace@mail.test", "phone": "6025552368", "date_of_birth": "1990-04-07" }, "address": { "address_line_1": "123 N Main St", "city": "Phoenix", "state": "AZ", "zip_code": "85004" }, "education": { "education_level": "bachelors", "high_school_graduation_year": "2008", "start_timeline": "1_3_months", "learning_preference": "online" }, "background": { "military_affiliation": "none", "us_citizen": "yes" } }, "tracking": { "ip_address": "203.0.113.9", "subid": "pub-42", "subid2": "creative-7", "utm_source": "partner", "utm_medium": "email", "utm_campaign": "fall-enrollment" }, "program_id": "4411", "tcpa_consent": true, "trusted_form_cert_url": "https://cert.trustedform.com/0123456789abcdef0123456789abcdef01234567" } } } } } }, "responses": { "200": { "description": "A decision: accepted, held (test) or refused. Read status and code.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "description": "ACCEPTED, or the reason it was not (DUPLICATE, NOT_ELIGIBLE, CAP_REACHED, BUYER_REJECTED, …)." }, "status": { "type": "string", "enum": [ "accepted", "saved", "pending", "held", "rejected", "invalid", "failed" ], "description": "The outcome, from one lower-case set." }, "reason": { "type": "string", "description": "A short sentence-case explanation, e.g. \"Missing HS grad year\" or \"Duplicate - Client\" (\" - Client\": the school's own system decided)." }, "success": { "type": "boolean" }, "accepted": { "type": "boolean" }, "retryable": { "type": "boolean" }, "icon_lead_id": { "type": "string" }, "payout": { "type": "number", "description": "Accepted: YOUR payout booked for this lead (absent when none is configured). Not accepted: 0. Never the offer's own price." }, "message": { "type": "string" }, "disposition": { "type": "object", "additionalProperties": true } }, "additionalProperties": true, "example": { "code": "ACCEPTED", "status": "accepted", "reason": "Lead accepted", "success": true, "accepted": true, "retryable": false, "icon_lead_id": "1e8d30bb-7c5f-41b9-8cf1-5e6b57abe999", "payout": 28, "message": "Lead processed successfully" } }, "examples": { "accepted": { "value": { "code": "ACCEPTED", "status": "accepted", "reason": "Lead accepted", "success": true, "accepted": true, "retryable": false, "icon_lead_id": "5a2c7e91-3b4d-4f6a-9c8e-2d1f0b7a6e53", "payout": 28, "message": "Lead processed successfully" } }, "refused": { "value": { "code": "DUPLICATE", "status": "rejected", "reason": "Duplicate - Offer", "source": "icon", "success": false, "accepted": false, "retryable": false, "icon_lead_id": "5a2c7e91-3b4d-4f6a-9c8e-2d1f0b7a6e53", "payout": 0, "message": "Duplicate lead" } } } } } }, "400": { "description": "REQUIRED_FIELD_MISSING / INVALID_FIELD (the field is named).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "401": { "description": "AUTH_REQUIRED (no API key) or AUTH_INVALID (a key ICON does not know); status invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "403": { "description": "FORBIDDEN: the campaign or offer is not yours, icon_affiliate_id is not your key's affiliate, the campaign you named is not one of the result's (error \"result_campaign_mismatch\"), or the lead was already submitted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "404": { "description": "NOT_FOUND: the result, lead or offer is unknown to your key (another affiliate's result answers error \"search_result_not_found\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "409": { "description": "MALFORMED_REQUEST: send search_lead_id (the icon_lead_id of the search the result came from).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "429": { "description": "RATE_LIMITED (retryable): this API key is over its rate limit. Wait the Retry-After header's seconds (also retry_after_seconds) and retry. Limits are per API key and per leg: search 60 per minute with bursts of up to 10, results polling 600 per minute, submit 120 per minute, unless ICON set other limits for your key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "500": { "description": "INTERNAL_ERROR (request_id identifies it to ICON support).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "503": { "description": "UNAVAILABLE: retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } } } } }, "/api/v1/engine/dupe-check": { "post": { "summary": "Duplicate pre-check", "tags": [ "Lead submission" ], "description": "Ask whether ICON would call a lead a duplicate before posting it. Server to server only. Send any of the lead's fields raw, and/or hashed under \"hashed\" (lower-case hex SHA-256 of the published normalized form). Answers duplicate_likely only; submit always runs the full check. Hashing forms: https://developers.iconroute.io/api/dupe-check/", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "offer_id": { "type": "string", "format": "uuid", "description": "Optional: one of your offers (for an offer-scoped policy)." }, "email": { "type": "string" }, "phone": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "zip": { "type": "string" }, "address": { "type": "string" }, "dob": { "type": "string", "description": "YYYY-MM-DD or MM/DD/YYYY." }, "hashed": { "type": "object", "additionalProperties": { "type": "string", "description": "SHA-256 hex of the normalized value." } } }, "additionalProperties": true } } } }, "responses": { "200": { "description": "OK: duplicate_likely only.", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "example": "OK" }, "status": { "type": "string", "enum": [ "accepted", "saved", "pending", "held", "rejected", "invalid", "failed" ], "description": "The outcome, from one lower-case set.", "example": "accepted" }, "reason": { "type": "string", "description": "A short sentence-case explanation, e.g. \"Missing HS grad year\" or \"Duplicate - Client\" (\" - Client\": the school's own system decided).", "example": "OK" }, "success": { "type": "boolean" }, "duplicate_likely": { "type": "boolean" }, "retryable": { "type": "boolean" } } } } } }, "400": { "description": "MALFORMED_REQUEST: no usable lead field was sent (raw or hashed); INVALID_FIELD: offer_id is not a UUID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "401": { "description": "AUTH_REQUIRED (no API key) or AUTH_INVALID (a key ICON does not know); status invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "403": { "description": "FORBIDDEN: the offer_id is not yours, or this key is not permitted to use the pre-check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "404": { "description": "Not found: the pre-check is not available on your account; ask your ICON contact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "405": { "description": "MALFORMED_REQUEST: use POST.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "413": { "description": "The body is over 16 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "429": { "description": "RATE_LIMITED (retryable): this key is over its pre-check limit. Wait the Retry-After seconds and retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } }, "503": { "description": "UNAVAILABLE (retryable): the check could not run. Retry, or post the lead: submit runs the full check.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardError" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Your ICON API key." } }, "schemas": { "Lead": { "type": "object", "properties": { "background": { "type": "object", "properties": { "rn_license": { "type": "string", "enum": [ "rn", "lpn_lvn", "no" ] }, "military_affiliation": { "type": "string", "enum": [ "none", "affiliated", "active_duty", "veteran", "spouse_dependent" ] }, "us_citizen": { "type": "string", "enum": [ "yes", "no" ] }, "has_internet_access": { "type": "string", "enum": [ "yes", "no" ] } }, "additionalProperties": true }, "education": { "type": "object", "properties": { "teaching_certificate": { "type": "string", "enum": [ "yes", "no" ] }, "education_level": { "type": "string", "enum": [ "no_hs_diploma", "ged", "high_school", "some_college", "associates", "bachelors", "masters", "doctorate" ] }, "start_timeline": { "type": "string", "enum": [ "immediately", "1_3_months", "4_6_months", "7_12_months", "over_1_year", "not_sure" ] }, "learning_preference": { "type": "string", "enum": [ "online", "campus", "either" ] }, "high_school_graduation_year": { "type": "string", "description": "Four digits, e.g. 2012." } }, "additionalProperties": true }, "personal": { "type": "object", "properties": { "email": { "type": "string", "description": "An email address." }, "phone": { "type": "string", "description": "The 10-digit US number, digits only (e.g. 6025552368)." }, "first_name": { "type": "string", "description": "Text." }, "last_name": { "type": "string", "description": "Text." }, "date_of_birth": { "type": "string", "description": "YYYY-MM-DD." }, "age": { "type": "string", "description": "Whole number of years." }, "gender": { "type": "string", "enum": [ "female", "male" ] } }, "additionalProperties": true }, "address": { "type": "object", "properties": { "address_line_1": { "type": "string", "description": "The street line." }, "address_line_2": { "type": "string", "description": "Unit / apartment line." }, "city": { "type": "string", "description": "Text." }, "state": { "type": "string", "enum": [ "AL", "AK", "AZ", "AR", "CA", "CO", "CT", "DE", "FL", "GA", "HI", "ID", "IL", "IN", "IA", "KS", "KY", "LA", "ME", "MD", "MA", "MI", "MN", "MS", "MO", "MT", "NE", "NV", "NH", "NJ", "NM", "NY", "NC", "ND", "OH", "OK", "OR", "PA", "RI", "SC", "SD", "TN", "TX", "UT", "VT", "VA", "WA", "WV", "WI", "WY", "DC", "AS", "GU", "MP", "PR", "VI", "UM" ], "description": "The two-letter US state code." }, "zip_code": { "type": "string", "description": "The 5-digit ZIP." } }, "additionalProperties": true } }, "additionalProperties": true }, "Tracking": { "type": "object", "properties": { "ip_address": { "type": "string", "description": "The consumer's own public IPv4 or IPv6 address (not your server's). Required from affiliates." }, "utm_source": { "type": "string", "description": "Text, trimmed; case is kept." }, "utm_medium": { "type": "string", "description": "Text, trimmed; case is kept." }, "utm_campaign": { "type": "string", "description": "Text, trimmed; case is kept." }, "utm_content": { "type": "string", "description": "Text, trimmed; case is kept." }, "utm_term": { "type": "string", "description": "Text, trimmed; case is kept." }, "gclid": { "type": "string", "description": "Text, trimmed; case is kept." }, "gbraid": { "type": "string", "description": "Text, trimmed; case is kept." }, "wbraid": { "type": "string", "description": "Text, trimmed; case is kept." }, "fbclid": { "type": "string", "description": "Text, trimmed; case is kept." }, "msclkid": { "type": "string", "description": "Text, trimmed; case is kept." }, "ttclid": { "type": "string", "description": "Text, trimmed; case is kept." }, "click_id": { "type": "string", "description": "Text, trimmed; case is kept." }, "subid": { "type": "string", "description": "Text, trimmed; case is kept." }, "subid2": { "type": "string", "description": "Text, trimmed; case is kept." }, "subid3": { "type": "string", "description": "Text, trimmed; case is kept." }, "subid4": { "type": "string", "description": "Text, trimmed; case is kept." }, "subid5": { "type": "string", "description": "Text, trimmed; case is kept." } }, "additionalProperties": true }, "ResultEntry": { "type": "object", "description": "One result. The same core fields whether the offer is hosted by ICON or is a partner offer ICON calls.", "properties": { "icon_result_id": { "type": "string", "description": "Submit this id to POST /api/v1/engine/leads." }, "campaign_id": { "type": [ "string", "null" ], "format": "uuid", "description": "The campaign the result is sold under." }, "offer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The ICON offer id." }, "name": { "type": "string" }, "offer_type": { "type": "string", "description": "shared | exclusive | true_exclusive" }, "is_exclusive": { "type": [ "boolean", "null" ] }, "tcpa_text": { "type": [ "string", "null" ], "description": "The consent statement to show with this result." } }, "additionalProperties": true }, "school": { "type": "object", "properties": { "name": { "type": "string" }, "logo_url": { "type": [ "string", "null" ] } }, "additionalProperties": true }, "programs": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string", "description": "Send as program_id on submit." }, "label": { "type": "string" }, "payout": { "type": "number", "description": "Your payout for this program. Absent when none is configured." } }, "required": [ "value", "label" ] } }, "payout": { "type": "number", "description": "Your best payout for this result (never the offer's own price). Absent when none is configured." }, "form_fields": { "type": "array", "description": "Questions this result needs answered on submit, by name.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "type": { "type": "string" }, "required": { "type": "boolean" }, "required_when": { "type": "object", "description": "Required only when one of these programs is chosen.", "properties": { "program_ids": { "type": "array", "items": { "type": "string" } } } }, "options": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" } } } } }, "required": [ "name", "type", "required" ] } }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Submit before this time." } }, "required": [ "icon_result_id", "offer", "programs", "form_fields" ], "additionalProperties": true, "example": { "icon_result_id": "api-0b7e4a2c-981234", "campaign_id": "6f1c2d3e-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "offer": { "id": "0b7e4a2c-9d8f-4e1a-b2c3-d4e5f6a7b8c9", "name": "Example University", "offer_type": "shared", "is_exclusive": false, "tcpa_text": "By clicking Submit, I agree…" }, "school": { "name": "Example University", "logo_url": "https://cdn.example.com/logo.png" }, "programs": [ { "value": "4411", "label": "BS Business (Online)", "payout": 28 } ], "payout": 28, "form_fields": [ { "name": "api_field_military", "label": "Military affiliation", "type": "select", "required": true, "options": [ { "value": "none", "label": "None" } ] }, { "name": "api_field_rn_license", "label": "RN license?", "type": "select", "required": false, "required_when": { "program_ids": [ "4411" ] } } ], "expires_at": "2026-09-25T20:15:00Z" } }, "ResultsEnvelope": { "type": "object", "properties": { "code": { "type": "string", "example": "OK" }, "status": { "type": "string", "enum": [ "accepted", "saved", "pending", "held", "rejected", "invalid", "failed" ], "description": "The outcome, from one lower-case set.", "example": "accepted" }, "reason": { "type": "string", "description": "A short sentence-case explanation, e.g. \"Missing HS grad year\" or \"Duplicate - Client\" (\" - Client\": the school's own system decided).", "example": "OK" }, "processing_done": { "type": "boolean", "description": "False while API offers are still answering: poll /engine/results again." }, "poll_after_ms": { "type": "integer", "description": "Present while processing_done is false: wait this long before the next poll." }, "icon_lead_id": { "type": "string", "format": "uuid", "description": "Your search id: poll with it, and send it as search_lead_id on submit." }, "accepted_count": { "type": "integer" }, "max_accepted_submissions": { "type": "integer" }, "true_exclusive_accepted": { "type": "boolean" }, "offers": { "type": "array", "items": { "$ref": "#/components/schemas/ResultEntry" } } }, "additionalProperties": true }, "StandardError": { "type": "object", "properties": { "code": { "type": "string", "description": "The standardized code." }, "status": { "type": "string", "enum": [ "accepted", "saved", "pending", "held", "rejected", "invalid", "failed" ], "description": "The outcome, from one lower-case set." }, "reason": { "type": "string", "description": "A short sentence-case explanation, e.g. \"Missing HS grad year\" or \"Duplicate - Client\" (\" - Client\": the school's own system decided)." }, "message": { "type": "string" }, "retryable": { "type": "boolean" }, "field": { "type": "string", "description": "The field at fault, when one is." }, "retry_after_seconds": { "type": "integer", "description": "RATE_LIMITED only: seconds to wait before retrying (the Retry-After header)." }, "request_id": { "type": "string" } }, "additionalProperties": true } } } }