> ## Documentation Index > Fetch the complete documentation index at: https://docs.younegotiate.com/llms.txt > Use this file to discover all available pages before exploring further. # Start consumer login > Match a consumer profile by last name, date of birth, and last four SSN digits. A matched profile returns a flow token and may send OTP immediately. If the request includes a valid trusted-device cookie for the matched profile, the backend returns an access token immediately without sending OTP. A login miss returns an attempt token so the client can ask the user to confirm profile creation. ## OpenAPI ````yaml /api/consumer.openapi.yaml post /auth/login openapi: 3.1.0 info: title: YouNegotiate Consumer API version: '2.0' description: >- Stateless API endpoints for consumer portal authentication and account access. servers: - url: https://api.consumer.younegotiate.com description: Production security: [] tags: - name: System description: Public consumer domain system and health endpoints. - name: Authentication description: >- Consumer identity matching, contact capture, OTP verification, token creation, and logout endpoints. - name: Profile - My ecoAddress description: Consumer profile tab for signed-in identity / ecoAddress context. - name: Profile - Communication Controls description: >- Consumer profile tab for communication permissions, email/mobile changes, and email/mobile verification. - name: Profile - My Billing Details description: >- Consumer profile tab for billing name and billing address details used for payment verification. - name: Profile - Personalize My Portal description: Consumer profile tab for portal colors and profile image personalization. - name: Accounts description: Consumer-owned account list and account detail endpoints. - name: Bill Pay Wallet description: >- Consumer Bill Pay Wallet saved payment profiles and scheduled payment method update endpoints. - name: Upcoming Payments description: >- Consumer My Bill Pay Calendar upcoming-payment rows and calendar display data. - name: Calendar Sync description: >- Consumer Google and Microsoft calendar connection, OAuth callback, and live-update endpoints. - name: Gift Registry description: >- Consumer Bill Pay Gift Registry account list, shared registry, and Helping Hand link endpoints. - name: EcoMailbox description: Consumer MyEcoMailBox list endpoints and unread sidebar badge state. - name: Notice Responses description: >- Consumer My Account notice-response wizard endpoints for sender details and account details. paths: /auth/login: post: tags: - Authentication summary: Start consumer login description: >- Match a consumer profile by last name, date of birth, and last four SSN digits. A matched profile returns a flow token and may send OTP immediately. If the request includes a valid trusted-device cookie for the matched profile, the backend returns an access token immediately without sending OTP. A login miss returns an attempt token so the client can ask the user to confirm profile creation. operationId: consumerLogin requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LoginConsumerRequest' example: last_name: Weaver dob: '1984-07-14' last_four_ssn: '1234' recaptcha: recaptcha-token responses: '200': description: Login flow started, contact input required, or no match returned. content: application/json: schema: $ref: '#/components/schemas/ConsumerLoginResponse' examples: loginWithOtp: summary: With OTP - existing profile value: message: OTP sent successfully to j***@example.com. matched: true flow_token: consumer-flow-token otp_sent: true channel: email masked_destination: j***@example.com needsContactBeforeOtp: summary: With OTP - contact required first value: message: Contact information is required before verification. matched: true flow_token: consumer-flow-token requires_contact_input: true loginWithoutOtpTrustedDevice: summary: Without OTP - trusted browser value: message: Logged in. matched: true trusted_device: true meta: access_token: 1|consumer-access-token token_type: Bearer noMatch: summary: Without OTP - no matching profile value: message: No matching consumer profile found. matched: false attempt_token: consumer-attempt-token '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/TooManyRequests' components: schemas: LoginConsumerRequest: type: object required: - last_name - dob - last_four_ssn - recaptcha properties: last_name: type: string maxLength: 50 description: Consumer last name. Matching is case-insensitive in the backend. dob: type: string format: date description: >- Consumer date of birth in `YYYY-MM-DD` format. The consumer must be at least 18 years old. last_four_ssn: type: string pattern: ^\d{4}$ description: Last four SSN digits. Non-digits are stripped before validation. recaptcha: type: string ConsumerLoginResponse: title: Consumer Login Response oneOf: - $ref: '#/components/schemas/ConsumerLoginWithOtpResponse' - $ref: '#/components/schemas/ConsumerLoginNeedsContactResponse' - $ref: '#/components/schemas/ConsumerLoginTrustedDeviceResponse' - $ref: '#/components/schemas/ConsumerLoginNoMatchResponse' ConsumerLoginWithOtpResponse: title: Login With OTP type: object required: - message - matched - flow_token - otp_sent - channel - masked_destination properties: message: type: string example: OTP sent successfully to j***@example.com. matched: type: boolean enum: - true flow_token: type: string otp_sent: type: boolean enum: - true channel: $ref: '#/components/schemas/ConsumerOtpChannel' masked_destination: type: string ConsumerLoginNeedsContactResponse: title: Contact Required Before OTP type: object required: - message - matched - flow_token - requires_contact_input properties: message: type: string example: Contact information is required before verification. matched: type: boolean enum: - true flow_token: type: string requires_contact_input: type: boolean enum: - true ConsumerLoginTrustedDeviceResponse: title: Login Without OTP - Trusted Device type: object required: - message - matched - trusted_device - meta properties: message: type: string example: Logged in. matched: type: boolean enum: - true trusted_device: type: boolean enum: - true meta: type: object required: - access_token - refresh_token - token_type - access_token_expires_at - refresh_token_expires_at properties: access_token: type: string refresh_token: type: string description: >- Plaintext refresh token returned once. Store securely and send to POST /auth/refresh. token_type: type: string example: Bearer access_token_expires_at: type: - string - 'null' format: date-time description: >- Access token expiry timestamp when an expiry is assigned; otherwise null. refresh_token_expires_at: type: string format: date-time ConsumerLoginNoMatchResponse: title: No Matching Profile type: object required: - message - matched - attempt_token properties: message: type: string example: No matching consumer profile found. matched: type: boolean enum: - false attempt_token: type: string description: >- Token returned so the frontend can ask the consumer to confirm profile creation. ValidationErrorResponse: type: object required: - message - errors properties: message: type: string errors: type: object additionalProperties: type: array items: type: string MessageResponse: type: object required: - message properties: message: type: string ConsumerOtpChannel: type: string enum: - email - mobile nullable: true responses: ValidationError: description: Request validation failed. content: application/json: schema: $ref: '#/components/schemas/ValidationErrorResponse' TooManyRequests: description: Request was rate limited. content: application/json: schema: $ref: '#/components/schemas/MessageResponse' ````