> ## Documentation Index > Fetch the complete documentation index at: https://docs.bango.com/llms.txt > Use this file to discover all available pages before exploring further. # Send an eligibility request to a partner > The Bango Platform uses this endpoint to send an eligibility request to a partner. Every request sent may result in a range of possible responses from the partner. Every request will include a unique `requestId` property (UUID v4). This identifies the request and is not used for any other purpose. The corresponding response to the request must include the `requestId`. ### HTTP responses The Bango Platform always sends a request to the partner over HTTP, and the partner must return an HTTP response. HTTP requests contain request types as defined in this specification. The HTTP response MUST be one of the following: - HTTP 200 OK - containing a response payload in the response body. Each request defines the expected responses - HTTP 4xx - indicating a problem with the request - HTTP 5xx - indicating a problem with the partner system This specification defines the shape of HTTP 4xx and 5xx responses. These all have a response body containing an `errors` array, each member of which is an object containing an error `code` and other data. If a request to a partner times out, this is treated the same as an HTTP 503 error from the partner with `canRetry: true`. #### HTTP 400 BAD REQUEST responses For HTTP 400 BAD REQUEST responses specifically, the partner MUST use these values for `code` for the error conditions listed: - `invalid-json` - If the request body isn't valid JSON format - `missing-parameter` - If any required parameter is not present in the request body. For example, `id`, `type`, `payload`, or any required value inside `payload`. - `invalid-parameter` - If any parameter in the request is syntactically invalid. For example, if `type` is an integer, or if `id` is not a UUID v4. - If any parameter in the request is semantically invalid. For example, if a `payload` field specifies a user identifier and that user isn't recognized by the partner. #### HTTP 5xx responses HTTP 5xx responses may indicate a problem on the partner's side. This might be a temporary problem caused by a network issue between the Bango Platform and the partner, or it may indicate a more serious, persistent issue. Any 5xx response from the partner propagates through the platform as a service error with code `partner-failure`. The 5xx response from the partner may specify that the request can be retried, using the `metadata.canRetry` boolean in the 5xx response. A timeout in the connection from the Bango Platform to the partner is always reported as a `partner-failure` that may be retried. ## OpenAPI ````yaml /openapi/current/dvm/dvm-to-reseller/eligibility/openapi.yaml post /{partnerUrlForEligibilityCheck} openapi: 3.1.0 info: title: Outbound Eligibility API version: v1.0.0-draft description: | The Outbound Eligibility API (OEA) is an interface definition for a service that partner implements on their own servers. It defines how the Bango Platform sends all types of consumer eligibility requests to partners. # Change log **2025-04-21** | v.0.0.3 - Formatting fixes **2025-02-06** | v.0.0.2 - Add user-terminated code for ELIGIBILITY_DENIED - Support optional billingIdentifier field in request - Additional fields **2024-11-15** | v.0.0.1 - Updated Outbound-Eligibility-API request/response models servers: - description: Testing environment url: https://api.sandbox.bango.com security: - BasicAuth: [] paths: /{partnerUrlForEligibilityCheck}: post: summary: Send an eligibility request to a partner description: > The Bango Platform uses this endpoint to send an eligibility request to a partner. Every request sent may result in a range of possible responses from the partner. Every request will include a unique `requestId` property (UUID v4). This identifies the request and is not used for any other purpose. The corresponding response to the request must include the `requestId`. ### HTTP responses The Bango Platform always sends a request to the partner over HTTP, and the partner must return an HTTP response. HTTP requests contain request types as defined in this specification. The HTTP response MUST be one of the following: - HTTP 200 OK - containing a response payload in the response body. Each request defines the expected responses - HTTP 4xx - indicating a problem with the request - HTTP 5xx - indicating a problem with the partner system This specification defines the shape of HTTP 4xx and 5xx responses. These all have a response body containing an `errors` array, each member of which is an object containing an error `code` and other data. If a request to a partner times out, this is treated the same as an HTTP 503 error from the partner with `canRetry: true`. #### HTTP 400 BAD REQUEST responses For HTTP 400 BAD REQUEST responses specifically, the partner MUST use these values for `code` for the error conditions listed: - `invalid-json` - If the request body isn't valid JSON format - `missing-parameter` - If any required parameter is not present in the request body. For example, `id`, `type`, `payload`, or any required value inside `payload`. - `invalid-parameter` - If any parameter in the request is syntactically invalid. For example, if `type` is an integer, or if `id` is not a UUID v4. - If any parameter in the request is semantically invalid. For example, if a `payload` field specifies a user identifier and that user isn't recognized by the partner. #### HTTP 5xx responses HTTP 5xx responses may indicate a problem on the partner's side. This might be a temporary problem caused by a network issue between the Bango Platform and the partner, or it may indicate a more serious, persistent issue. Any 5xx response from the partner propagates through the platform as a service error with code `partner-failure`. The 5xx response from the partner may specify that the request can be retried, using the `metadata.canRetry` boolean in the 5xx response. A timeout in the connection from the Bango Platform to the partner is always reported as a `partner-failure` that may be retried. operationId: send-request-outbound parameters: - in: path name: partnerUrlForEligibilityCheck required: true description: | URL used to perform the eligibility check. schema: type: string requestBody: description: > A request initiated by the Bango Platform, to be processed by the partner. The following request types are available. See each request type schema for detailed information on purpose and response payload types. - `OFFERS_ELIGIBILITY_CHECK`: Ask the partner up-to-date eligibility data across for a specific offer or for all available offers for a consumer. required: true content: application/json: schema: oneOf: - $ref: '#/components/schemas/OFFERS_ELIGIBILITY_CHECK' responses: '200': description: | The response payload, which depends on the request type. Supported HTTP responses - HTTP 200 OK: - `ELIGIBILITY_RETRIEVED` - `ELIGIBILITY_DENIED` content: application/vnd.bango.partner-response.v1+json: schema: oneOf: - $ref: '#/components/schemas/ELIGIBILITY_RETRIEVED' - $ref: '#/components/schemas/ELIGIBILITY_DENIED' '400': $ref: '#/components/responses/BadRequestErrorResponse' description: | The response payload, which depends on the request type. Supported HTTP responses - HTTP 400 BAD REQUEST with one or more errors: - `code` == `invalid-json`: - the request body is not valid JSON - `code` == `missing-parameter`: - a required parameter is omitted from the request payload - `code` == `invalid-parameter`: - a parameter is not of the expected type, or - a parameter violates the documented constraints - `consumer.consumerId` does not identify a consumer known to the partner '401': $ref: '#/components/responses/InvalidCredentialsErrorResponse' '403': $ref: '#/components/responses/PermissionDeniedErrorResponse' '429': $ref: '#/components/responses/TooManyRequestsErrorResponse' '500': description: | An internal server error occurred content: application/json: schema: type: object properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/partner-internal-server-error' - $ref: '#/components/schemas/partner-failure' required: - errors '503': $ref: '#/components/responses/PartnerServiceUnavailableErrorResponse' components: schemas: OFFERS_ELIGIBILITY_CHECK: title: OFFERS_ELIGIBILITY_CHECK request payload (outbound) description: > Ask the partner for all available offers eligibility up-to-date for a consumer. The consumer is identified using consumer properties that contains the identification of the consumer, frequently the consumerId. type: object properties: requestId: $ref: '#/components/schemas/request-id' type: description: | Indicates the type of the eligibility check being requested. type: string enum: - OFFERS_ELIGIBILITY_CHECK example: OFFERS_ELIGIBILITY_CHECK payload: type: object properties: consumer: $ref: '#/components/schemas/consumer-properties' description: | Identification data to identify the consumer. type: object offers: $ref: '#/components/schemas/offers-ids-properties' description: | List of offers for which eligibility is checked. additionalProperties: false required: - consumer required: - requestId - type - payload ELIGIBILITY_RETRIEVED: title: ELIGIBILITY_RETRIEVED response payload description: > This is one of the two responses to an `OFFERS_ELIGIBILITY_CHECK` request. It Contains information about the consumer's eligibility for offers. This response is used when any eligibility information was provided by the partner. type: object properties: requestId: $ref: '#/components/schemas/request-id' type: const: ELIGIBILITY_RETRIEVED description: Indicates the type of eligibility response. payload: type: object properties: eligibilityData: $ref: '#/components/schemas/eligibility-data' additionalProperties: false required: - requestId - type - payload ELIGIBILITY_DENIED: title: ELIGIBILITY_DENIED response payload description: > This is the other possible responses to an `OFFERS_ELIGIBILITY_CHECK` request. Contains information about the consumer's eligibility denial reason. This response is used when partner has denied an eligibility check due to some reason. type: object properties: requestId: $ref: '#/components/schemas/request-id' type: const: ELIGIBILITY_DENIED payload: type: object properties: code: $ref: '#/components/schemas/eligibility-denied-code' message: description: | Message describing reason for denying an eligibility check. type: string minLength: 1 maxLength: 256 example: user has not paid their bill additionalProperties: false required: - code required: - requestId - type partner-internal-server-error: title: internal-server-error [PP] description: Internal server error type: object properties: code: const: internal-server-error originator: description: Additional information to help identify the error origin type: string example: PARTNER metadata: description: Additional information to help identify the specific error case type: object properties: canRetry: description: Whether the partner believes the request can be retried type: boolean default: false message: description: Human-readable message describing the error type: string example: >- The server encountered an unexpected condition which prevented it from fulfilling the request required: - code - meta - message partner-failure: title: partner-failure description: Partner failed type: object properties: code: const: partner-failure originator: description: Additional information to help identify the error origin type: string example: PARTNER metadata: description: Additional information to help identify the specific error case type: object properties: canRetry: description: Whether the request can be retried type: boolean default: true partnerCode: $ref: '#/components/schemas/partner-code' message: description: Human-readable message describing the error type: string example: >- The partner encountered an unexpected condition which prevented it from fulfilling the request required: - code - metadata - message request-id: title: Request ID description: | Unique ID associated with request/response to an API. type: string format: uuid example: 85d814e6-7ca7-4753-8477-5363b67a6091 consumer-properties: title: consumer description: | Consumer identification data to identify the customer. type: object minProperties: 0 maxProperties: 50 unevaluatedProperties: type: string minLength: 1 maxLength: 512 properties: consumerIdentifier: $ref: '#/components/schemas/consumer-identifier' billingIdentifier: $ref: '#/components/schemas/billing-identifier' required: - consumerIdentifier example: consumerIdentifier: '123456789778' billingIdentifier: '08217467445' offers-ids-properties: title: list of offers ids description: > List of offers for which eligibility is checked. MUST contain at least one property. All property values MUST be strings. type: object minProperties: 1 maxProperties: 50 unevaluatedProperties: type: string minLength: 1 maxLength: 512 properties: offerId: $ref: '#/components/schemas/offer-id' required: - offerId example: - offerId: a49f0143-7d98-48c1-9f5a-5431294a823c - offerId: 8aa12c97-2027-47db-9df8-d62b5205e9fb eligibility-data: title: Eligibility Data description: | Describes the eligibility check data. type: object properties: offerEligibility: type: object description: Offer(s) eligibility information for the consumer. properties: expiryPeriod: type: string description: Period for which the offer(s) eligibility is valid for example: 20D offers: type: array description: > list of all available offers returned by the partner after an eligibility check. items: allOf: - $ref: '#/components/schemas/offers-properties' example: - offerId: a49f0143-7d98-48c1-9f5a-5431294a823c eligibilityStatus: CONSUMER_ELIGIBLE - offerId: 8aa12c97-2027-47db-9df8-d62b5205e9fb eligibilityStatus: CONSUMER_ELIGIBLE paymentEligibility: type: object description: >- Payment eligibility relevant to the billing identifier (if provided in the request). properties: status: $ref: '#/components/schemas/eligibility-status' expiryPeriod: type: string description: Period for which the payment(s) eligibility is valid for. example: 30D userProperties: $ref: '#/components/schemas/user-properties' eligibility-denied-code: title: Eligibility denied code description: > Defines the reason why a partner has denied an eligibility check. - `user-suspended`: The user has been suspended - `user-terminated`: The user has been terminated - `unsupported`: The partner cannot support eligibility checks - `unknown`: The partner has not provided information about eligibility status type: string minLength: 1 maxLength: 50 enum: - user-suspended - user-terminated - unsupported - unknown example: user-suspended BadRequest: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/invalid-json' - $ref: '#/components/schemas/missing-parameter' - $ref: '#/components/schemas/invalid-parameter' InvalidCredentials: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/invalid-credentials' PermissionDenied: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/permission-denied' TooManyRequests: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/too-many-requests' partner-code: title: Partner code description: > Code indicating the type of response the Bango Platform received from the partner. type: string example: service-unavailable PartnerServiceUnavailable: allOf: - $ref: '#/components/schemas/CommonErrorResponse' - properties: errors: type: array items: oneOf: - $ref: '#/components/schemas/partner-service-unavailable' consumer-identifier: title: Consumer Identifier description: > A consumer identifier is a unique id that identifies the consumer. It should be a unique value that is not reused between individuals, e.g. an account number, a user ID, a UUID, an ACR (Account Reference Code) or something similar. type: string minLength: 1 maxLength: 400 example: 1007189i2391836 billing-identifier: title: Billing Identifier description: > A consumer's billing identifier is a string that identifies a consumer's billing account. It could be a subscriber/account number. type: string minLength: 1 maxLength: 400 example: 8899334455 offer-id: title: Unique offer identifier description: | The unique identifier for the offer. type: string format: uuid example: 2adf1639-bb50-4df7-b8a0-79a0cd4f2277 offers-properties: title: list of offers eligibility properties description: > MUST contain at least two properties. MAY contain more than two properties. All property values MUST be strings. type: object minProperties: 1 maxProperties: 50 unevaluatedProperties: type: string minLength: 1 maxLength: 512 properties: offerId: $ref: '#/components/schemas/offer-id' eligibilityStatus: description: | Indicates the eligibility status of the offer. type: string enum: - CONSUMER_ELIGIBLE - CONSUMER_NOT_ELIGIBLE - CONSUMER_ELIGIBILITY_UNKNOWN - CONSUMER_ELIGIBILITY_UNSUPPORTED example: CONSUMER_ELIGIBLE message: description: > Optional message to indicate why the consumer is not eligible for the offer. type: string minLength: 1 maxLength: 256 example: >- Unfortunately you are not eligible to redeem this offer as you are not a Super Mega Plus customer required: - offerId - eligibilityStatus example: offerId: a49f0143-7d98-48c1-9f5a-5431294a823c eligibilityStatus: CONSUMER_ELIGIBLE eligibility-status: title: Payment Eligibility Status description: > Status of the consumer's billing identifier for payments processing. - `enabled`: Authorized partners can use the billing identifier to process payments - `not-enabled`: Authorized partners cannot use the billing identifier to process payments - `closed`: The billing identifier can no longer process payments - `barred`: The partner has suspended or barred the billing identifier (this may be temporary) - `unknown`: The partner has not provided information about eligibility status - `unsupported`: The partner does not support requests about payments eligibility type: string enum: - enabled - not-enabled - closed - barred - unknown - unsupported example: enabled user-properties: title: User Properties description: | Describes the User Properties data. type: object properties: accountType: $ref: '#/components/schemas/account-type' countryCode: $ref: '#/components/schemas/country-code-iso-3166' locale: $ref: '#/components/schemas/locale-bcp-47' currency: $ref: '#/components/schemas/currency-code-iso-4217' customerProfile: $ref: '#/components/schemas/customer-profile' CommonErrorResponse: type: object required: - errors invalid-json: title: invalid-json description: The request body is not valid JSON type: object properties: code: const: invalid-json originator: description: Additional information to help identify the error origin type: string example: PARTNER metadata: description: >- Additional information to help identify the specific error case (empty in this case) type: object message: description: Human-readable message describing the error type: string example: The request body is not valid JSON required: - code - metadata - message missing-parameter: title: missing-parameter description: A required parameter is missing from the request type: object properties: code: const: missing-parameter originator: description: Additional information to help identify the error origin type: string example: PARTNER metadata: description: Additional information to help identify the specific error case type: object properties: param: description: The name of the missing parameter type: string required: - param message: description: Human-readable message describing the error type: string example: A required parameter was missing from the request required: - code - meta - message invalid-parameter: title: invalid-parameter description: A request parameter is invalid type: object properties: code: const: invalid-parameter originator: description: Additional information to help identify the error origin type: string example: PARTNER metadata: description: Additional information to help identify the specific error case type: object properties: param: description: The name of the invalid parameter type: string reason: description: >- Optional human-readable information to explain why the parameter is invalid. Code must not rely on the content of this string. type: string example: 'Expected format: YYYY-MM-DD' required: - param message: description: Human-readable message describing the error type: string example: A parameter in the request was not valid required: - code - metadata - message invalid-credentials: title: invalid-credentials description: Authentication error - invalid credentials type: object properties: code: const: invalid-credentials originator: description: Additional information to help identify the error origin type: string example: PARTNER metadata: description: >- Additional information to help identify the specific error case (empty in this case) type: object message: description: Human-readable message describing the error type: string example: The supplied credentials are not valid required: - code - metadata - message permission-denied: title: permission-denied description: Authorization error - permission denied type: object properties: code: const: permission-denied originator: description: Additional information to help identify the error origin type: string example: PARTNER metadata: description: >- Additional information to help identify the specific error case (empty in this case) type: object message: description: Human-readable message describing the error type: string example: The client is not permitted to perform this operation required: - code - metadata - message too-many-requests: title: too-many-requests description: Too many requests type: object properties: code: const: too-many-requests originator: description: Additional information to help identify the error origin type: string example: PARTNER metadata: description: >- Additional information to help identify the specific error case (empty in this case) type: object message: description: Human-readable message describing the error type: string example: Request limit reached. Please try again later required: - code - metadata - message partner-service-unavailable: title: service-unavailable [PP] description: Service is unavailable type: object properties: code: const: service-unavailable originator: description: Additional information to help identify the error origin type: string example: PARTNER metadata: description: Additional information to help identify the specific error case type: object properties: canRetry: description: Whether the partner believes the request can be retried type: boolean default: false message: description: Human-readable message describing the error type: string example: >- The service is undergoing maintenance and is not available. Please try again later required: - code - metadata - message account-type: title: Partner Account Type description: > The account type allocated by the partner provider for a consumer's account. type: string enum: - prepaid - postpaid - unknown country-code-iso-3166: title: ISO 3166-1 alpha-2 country code description: > A two-character [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) country code. type: string enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CN - CX - CC - CO - KM - CG - CD - CK - CR - CI - HR - CU - CW - CY - CZ - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GM - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IR - IQ - IE - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - KP - KR - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MK - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - MP - 'NO' - OM - PK - PW - PS - PA - PG - PY - PE - PH - PN - PL - PT - PR - QA - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - SS - ES - LK - SD - SR - SJ - SZ - SE - CH - SY - TW - TJ - TZ - TH - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - US - UM - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW locale-bcp-47: title: BCP 47 language tag description: > A [BCP 47](https://en.wikipedia.org/wiki/IETF_language_tag) language tag. type: string minLength: 1 maxLength: 50 example: - en-US - ar-SA currency-code-iso-4217: title: ISO 4217 3-char currency code description: > A three-character [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency code. The allowed values are: - All current ISO 4217 codes except those for precious metals and bonds - ISO 4217 historical codes withdrawn since 2010 ISO 4217 publication: January 1, 2023 type: string enum: - AED - AFN - ALL - AMD - ANG - AOA - ARS - AUD - AWG - AZN - BAM - BBD - BDT - BGN - BHD - BIF - BMD - BND - BOB - BOV - BRL - BSD - BTN - BWP - BYN - BYR - BZD - CAD - CDF - CHE - CHF - CHW - CLF - CLP - CNY - COP - COU - CRC - CUC - CUP - CVE - CZK - DJF - DKK - DOP - DZD - EEK - EGP - ERN - ETB - EUR - FJD - FKP - GBP - GEL - GHS - GIP - GMD - GNF - GTQ - GYD - HKD - HNL - HRK - HTG - HUF - IDR - ILS - INR - IQD - IRR - ISK - JMD - JOD - JPY - KES - KGS - KHR - KMF - KPW - KRW - KWD - KYD - KZT - LAK - LBP - LKR - LRD - LSL - LTL - LVL - LYD - MAD - MDL - MGA - MKD - MMK - MNT - MOP - MRO - MRU - MUR - MVR - MWK - MXN - MXV - MYR - MZN - NAD - NGN - NIO - NOK - NPR - NZD - OMR - PAB - PEN - PGK - PHP - PKR - PLN - PYG - QAR - RON - RSD - RUB - RWF - SAR - SBD - SCR - SDG - SEK - SGD - SHP - SLE - SLL - SOS - SRD - SSP - STD - STN - SVC - SYP - SZL - THB - TJS - TMT - TND - TOP - TRY - TTD - TWD - TZS - UAH - UGX - USD - USN - USS - UYI - UYU - UYW - UZS - VED - VEF - VES - VND - VUV - WST - XAF - XCD - XDR - XFU - XOF - XPF - XSU - YER - ZAR - ZMK - ZMW - ZWL example: USD customer-profile: title: spending limit profile description: | Customer’s latest spending limit profile type: string maxLength: 50 example: saver responses: BadRequestErrorResponse: description: Bad request content: application/json: schema: $ref: '#/components/schemas/BadRequest' InvalidCredentialsErrorResponse: description: | Authentication error - invalid credentials content: application/json: schema: $ref: '#/components/schemas/InvalidCredentials' PermissionDeniedErrorResponse: description: > User is not authorized for this operation. This error occurs when you try to perform an operation on a resource, and you have permission to access the resource - but you don't have permission to perform the operation. For example, you may be authorized to `GET` the resource but not update it. (If you try to perform any operation on a resource you're not authorized to access, the API returns a 404 error.) content: application/json: schema: $ref: '#/components/schemas/PermissionDenied' TooManyRequestsErrorResponse: description: > Request limit reached. The request was not processed. This error occurs when you send too many requests in a short period of time. You should pause before sending further requests. content: application/json: schema: $ref: '#/components/schemas/TooManyRequests' PartnerServiceUnavailableErrorResponse: description: Service unavailable content: application/json: schema: $ref: '#/components/schemas/PartnerServiceUnavailable' securitySchemes: BasicAuth: type: http scheme: basic ````