# Assign Segment source: https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/assign_segment/index.md #### Overview {#overview} **Actors:** Issuer developer, Mastercard Global Benefits Platform **Preconditions:** Card exists and is associated to the ICA; the segment and its bundles have been pre-configured by Mastercard; no active segment is currently assigned to the card **Outcome:** The card is assigned to the specified segment; the associated benefit bundles are returned with their effective and expiry dates **Endpoint:** `POST /card-segments` --- use this endpoint to assign a segment for the first time; use [Replace Segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/replace_segment/index.md) if a segment is already active on the card Assigns benefits to a card by taking a card number, segment code and effective date in the input. The response is an array of bundles that are assigned to the card. At this time this endpoint supports exactly one segment code in the input. It is defined as an array for future support. Diagram assign_segment API Reference: `POST /card-segments`
### Assign a segment code with today's date where the card is not assigned to another segment. Most common use case. {#assign-a-segment-code-with-todays-date-where-the-card-is-not-assigned-to-another-segment-most-common-use-case} 1. Cardholder requests a new benefit be associated with their card. 2. Issuer sends a request with a card number, segment code and effective date as an input parameter. 3. Benefit Allocation Service API returns an array of bundles that are assigned to the card which contains segment benefit bundle codes assigned with effective and expiry dates of bundles. ## Effective date scenarios {#effective-date-scenarios} ### Assign a segment code with a future effective date where the card is not assigned to another segment. {#assign-a-segment-code-with-a-future-effective-date-where-the-card-is-not-assigned-to-another-segment} 1. Cardholder requests or qualifies for a card with a segment associated with their card. 2. Customer sends a request with a card number, segment code and the future effective date. 3. Benefit Allocation Service API returns the bundles assigned to the card with the requested future effective date. ### Assign a segment code with an effective date in the past where the card is not assigned to another segment or have overlapping dates with a previous segment. {#assign-a-segment-code-with-an-effective-date-in-the-past-where-the-card-is-not-assigned-to-another-segment-or-have-overlapping-dates-with-a-previous-segment} 1. Cardholder requests or qualifies for a card with a segment associated with their card. 2. Customer sends a request that includes the card number, segment code and effective date in the past. 3. Benefit Allocation Service API returns bundles assigned to the card with the requested effective date in the past. ### Assign a segment code that has a bundle with expiry date in the future. {#assign-a-segment-code-that-has-a-bundle-with-expiry-date-in-the-future} 1. Cardholder requests a new benefit be associated with their card. 2. Issuer sends a request with a card number, segment code and effective date as an input parameter. 3. Benefit Allocation Service API returns an array of bundles that are assigned to the card which contains segment benefit bundle codes assigned with the provided future dated effective date and existing expiry dates of bundles. ### Example Request \& Response {#example-request--response} **Request** (`POST /card-segments`): ```json { "cardNumber": 5291070000000000, "segments": [ { "code": "DART", "effectiveDate": "2023-08-08" } ] } ``` **Sandbox response** (`200 OK`): Note: The Sandbox returns a fixed generic mock response regardless of input values. Use MTF for real data validation. ```json { "bundles": [ { "code": "080815", "effectiveDate": "2023-08-08", "expiryDate": "2024-07-24" }, { "code": "087950", "effectiveDate": "2023-09-08", "expiryDate": "2024-08-18" } ] } ``` ### Error Notes {#error-notes} | **Error Code** | **Description** | **Recovery Action** | |----------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `12` | Cardholder can only have one active segment | A segment is already assigned --- use [Replace Segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/replace_segment/index.md) to change it, or [Cancel Segment](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/use-cases/segment-operations/cancel_segment/index.md) to remove it first | | `8` | Segment is not eligible for ICA listed | Confirm the segment code is configured by Mastercard for your ICA before retrying | | `37` | Required field missing, Card Number | Include `cardNumber` in the plaintext payload before encrypting | | `39` | Required field missing, Segment Code | Include `segments[].code` in the plaintext payload before encrypting | | `40` | Required field missing, Effective Date | Include `segments[].effectiveDate` in the plaintext payload before encrypting | | `58` | Signature verification failed | Verify the mTLS certificate, signing key, and encrypted request body before resending | ## Additional Information {#additional-information} Tip: The following operations are allowed to be performed after Assign Segment: **Replace Segment, Cancel Segment, Replace Card, Freeze/Unfreeze Card** 1. Look at the [API Reference](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/api-reference/index.md) for information on how to implement this use case. 2. Look at the [Responses Codes and Error Codes](https://developer.mastercard.com/benefit-allocation-service-mtls/documentation/code-and-formats/index.md) for acknowledgement responses.