# Send label

Sends the label to our servers for analysis to improve our recommendation system.

Endpoint: POST /label
Security: risk_access_token

## Security:

  - `risk_access_token` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `label_type` (string, required)
    Type of label to send, which contains additional information that helps to classify the subject as fraudulent or legitimate. The API accepts both the enum values below and the legacy values (`KNOWN_MALICIOUS`, `SUSPECTED_MALICIOUS`, `KNOWN_LEGIT`, `UNKNOWN`) for backward compatibility.
    Enum: "CONFIRMED_FRAUD", "SUSPECTED_FRAUD", "CONFIRMED_LEGIT", "UNDETERMINED"

  - `subject` (object, required)
    Subject of the label

  - `subject.type` (string, required)
    The subject type.
    Enum: "ACTION_ID", "CORRELATION_ID", "CAMPAIGN_ID", "USER_ID", "IP_ADDRESS", "VERIFICATION_SESSION_ID", "FRAUD_RING_ID"

  - `subject.value` (string, required)
    The subject value
    Example: a05f8ae1-718f-4c33-a20c-682df281af7c

  - `subject.recommendations` (array)
    For `FRAUD_RING_ID` labels only. Allows labeling actions with specific recommendation.

  - `subject.is_campaign_confirmed` (boolean)
    For `CAMPAIGN_ID` labels only. Defines whether or not to label actions related to the campaign.

  - `use_case` (string)
    Fraud scenario associated with the label. You can further classify the scenario by providing `sub_category` and, for supported scenarios, `attack_method`. For supported values and combinations, see [Specify fraud scenarios with labels](/guides/risk/label-fraud-scenarios).
    Enum: "ACCOUNT_TAKEOVER", "DEVICE_TAKEOVER", "FIRST_PARTY_FRAUD", "IDENTITY_THEFT", "MONEY_MULE", "BOT_ATTACK", "SYNTHETIC_IDENTITY", "SOCIAL_ENGINEERING", "NEW_ACCOUNT_FRAUD", "CREDENTIAL_STUFFING"

  - `sub_category` (string)
    Optional refinement of `use_case`. Valid values depend on the selected `use_case`. Do not provide this field for `MONEY_MULE` or `CREDENTIAL_STUFFING`. For supported values by use case, see [Specify fraud scenarios with labels](/guides/risk/label-fraud-scenarios).
    Enum: "PHISHING", "MALWARE", "CREDENTIAL_BREACH", "DEVICE_TAKEOVER", "SESSION_HIJACKING", "RECOVERY_ABUSE", "INVESTMENT_SCAM", "ROMANCE_SCAM", "TECH_SUPPORT_SCAM", "PAYMENT_SCAM", "IMPERSONATION_SCAM", "COERCION", "DATA_BREACH", "PHYSICAL_THEFT", "SOCIAL_ENGINEERING", "CHARGEBACK_FRIENDLY_FRAUD", "BUST_OUT_FRAUD", "ACCOUNT_AGING", "APPLICATION_KYC_FRAUD", "REFERRAL_ABUSE", "SIGNUP_BONUS_ABUSE", "REWARDS_MANIPULATION", "STOLEN_IDENTITY", "SYNTHETIC_IDENTITY", "MULE_ACCOUNT", "BONUS_PROMO_ABUSE", "OTHER"

  - `attack_method` (string)
    Optional attack method associated with the label. Valid values depend on the selected `sub_category`, or directly on `use_case` for `MONEY_MULE` and `CREDENTIAL_STUFFING`. Do not provide this field for `FIRST_PARTY_FRAUD`. For supported values and combinations, see [Specify fraud scenarios with labels](/guides/risk/label-fraud-scenarios).
    Enum: "PHISHING_EMAIL", "PHISHING_SMS", "PHISHING_VOICE", "PHISHING_QR", "KEYLOGGER", "TROJAN", "SPYWARE", "BROWSER_MALWARE", "COMBO_LIST", "PASSWORD_SPRAYING", "AUTOMATED_TESTING", "REMOTE_DESKTOP", "SCREEN_SHARING", "REMOTE_SHELL", "ROOTKIT", "MITM", "TOKEN_THEFT_XSS", "TOKEN_THEFT_MALWARE", "SESSION_FIXATION", "PHISHING_RECOVERY", "HELPDESK_SOCENG", "FLOW_EXPLOITATION", "PHONE", "SOCIAL_MEDIA", "FAKE_PLATFORM", "DATING_APP", "MESSAGING_APP", "FAKE_POPUP", "COLD_CALL", "EMAIL", "FAKE_INVOICE", "IMPERSONATION", "URGENT_TRANSFER", "BANK", "GOVERNMENT", "FAMILY_EMERGENCY", "INPERSON", "LIVE_PHONE", "DATA_BREACH", "PHYSICAL_THEFT", "SOCIAL_ENGINEERING", "PHISHING", "PHYSICAL_DOC_THEFT", "DOCUMENT_FABRICATION", "DATA_COMBINATION", "AI_GENERATED", "JOB_SCAM_RECRUITMENT", "ROMANCE_RECRUITMENT", "NETWORK_RECRUITMENT", "MULTI_ACCOUNT", "BOT_AUTOMATION", "JOB_SCAM", "ROMANCE_SCAM", "INVESTMENT_SCAM", "SELF_RECRUITED", "COERCED", "UNKNOWN", "OTHER"

  - `source` (string)
    Source of the information used to assign the label, such as manual review, customer complaints, chargebacks, another fraud system, automated detection, or law enforcement. For supported values and definitions, see [Specify fraud scenarios with labels](/guides/risk/label-fraud-scenarios).
    Enum: "MANUAL_REVIEW", "CUSTOMER_COMPLAINTS", "CHARGEBACKS", "OTHER_VENDORS", "AUTOMATED_DETECTION", "LAW_ENFORCEMENT"

## Response 201:

  - `201` (unknown)
    Label has been received and stored successfully.

## Response 201 fields (application/json):

  - `message` (string, required)

  - `label_id` (string, required)
    ID of the saved label

  - `label` (object, required)

  - `label.label_id` (string)
    ID of the saved label

  - `label.label_type` (string, required)
    Type of label to send, which contains additional information that helps to classify the subject as fraudulent or legitimate. The API accepts both the enum values below and the legacy values (`KNOWN_MALICIOUS`, `SUSPECTED_MALICIOUS`, `KNOWN_LEGIT`, `UNKNOWN`) for backward compatibility.
    Enum: "CONFIRMED_FRAUD", "SUSPECTED_FRAUD", "CONFIRMED_LEGIT", "UNDETERMINED"

  - `label.subject` (object, required)
    Subject of the label

  - `label.subject.type` (string, required)
    The subject type.
    Enum: "ACTION_ID", "CORRELATION_ID", "CAMPAIGN_ID", "USER_ID", "IP_ADDRESS", "VERIFICATION_SESSION_ID", "FRAUD_RING_ID"

  - `label.subject.value` (string, required)
    The subject value
    Example: a05f8ae1-718f-4c33-a20c-682df281af7c

  - `label.subject.recommendations` (array)
    For `FRAUD_RING_ID` labels only. Allows labeling actions with specific recommendation.

  - `label.subject.is_campaign_confirmed` (boolean)
    For `CAMPAIGN_ID` labels only. Defines whether or not to label actions related to the campaign.

  - `label.use_case` (string)
    Fraud scenario associated with the label. You can further classify the scenario by providing `sub_category` and, for supported scenarios, `attack_method`. For supported values and combinations, see [Specify fraud scenarios with labels](/guides/risk/label-fraud-scenarios).
    Enum: "ACCOUNT_TAKEOVER", "DEVICE_TAKEOVER", "FIRST_PARTY_FRAUD", "IDENTITY_THEFT", "MONEY_MULE", "BOT_ATTACK", "SYNTHETIC_IDENTITY", "SOCIAL_ENGINEERING", "NEW_ACCOUNT_FRAUD", "CREDENTIAL_STUFFING"

  - `label.sub_category` (string)
    Optional refinement of `use_case`. Valid values depend on the selected `use_case`. Do not provide this field for `MONEY_MULE` or `CREDENTIAL_STUFFING`. For supported values by use case, see [Specify fraud scenarios with labels](/guides/risk/label-fraud-scenarios).
    Enum: "PHISHING", "MALWARE", "CREDENTIAL_BREACH", "DEVICE_TAKEOVER", "SESSION_HIJACKING", "RECOVERY_ABUSE", "INVESTMENT_SCAM", "ROMANCE_SCAM", "TECH_SUPPORT_SCAM", "PAYMENT_SCAM", "IMPERSONATION_SCAM", "COERCION", "DATA_BREACH", "PHYSICAL_THEFT", "SOCIAL_ENGINEERING", "CHARGEBACK_FRIENDLY_FRAUD", "BUST_OUT_FRAUD", "ACCOUNT_AGING", "APPLICATION_KYC_FRAUD", "REFERRAL_ABUSE", "SIGNUP_BONUS_ABUSE", "REWARDS_MANIPULATION", "STOLEN_IDENTITY", "SYNTHETIC_IDENTITY", "MULE_ACCOUNT", "BONUS_PROMO_ABUSE", "OTHER"

  - `label.attack_method` (string)
    Optional attack method associated with the label. Valid values depend on the selected `sub_category`, or directly on `use_case` for `MONEY_MULE` and `CREDENTIAL_STUFFING`. Do not provide this field for `FIRST_PARTY_FRAUD`. For supported values and combinations, see [Specify fraud scenarios with labels](/guides/risk/label-fraud-scenarios).
    Enum: "PHISHING_EMAIL", "PHISHING_SMS", "PHISHING_VOICE", "PHISHING_QR", "KEYLOGGER", "TROJAN", "SPYWARE", "BROWSER_MALWARE", "COMBO_LIST", "PASSWORD_SPRAYING", "AUTOMATED_TESTING", "REMOTE_DESKTOP", "SCREEN_SHARING", "REMOTE_SHELL", "ROOTKIT", "MITM", "TOKEN_THEFT_XSS", "TOKEN_THEFT_MALWARE", "SESSION_FIXATION", "PHISHING_RECOVERY", "HELPDESK_SOCENG", "FLOW_EXPLOITATION", "PHONE", "SOCIAL_MEDIA", "FAKE_PLATFORM", "DATING_APP", "MESSAGING_APP", "FAKE_POPUP", "COLD_CALL", "EMAIL", "FAKE_INVOICE", "IMPERSONATION", "URGENT_TRANSFER", "BANK", "GOVERNMENT", "FAMILY_EMERGENCY", "INPERSON", "LIVE_PHONE", "DATA_BREACH", "PHYSICAL_THEFT", "SOCIAL_ENGINEERING", "PHISHING", "PHYSICAL_DOC_THEFT", "DOCUMENT_FABRICATION", "DATA_COMBINATION", "AI_GENERATED", "JOB_SCAM_RECRUITMENT", "ROMANCE_RECRUITMENT", "NETWORK_RECRUITMENT", "MULTI_ACCOUNT", "BOT_AUTOMATION", "JOB_SCAM", "ROMANCE_SCAM", "INVESTMENT_SCAM", "SELF_RECRUITED", "COERCED", "UNKNOWN", "OTHER"

  - `label.source` (string)
    Source of the information used to assign the label, such as manual review, customer complaints, chargebacks, another fraud system, automated detection, or law enforcement. For supported values and definitions, see [Specify fraud scenarios with labels](/guides/risk/label-fraud-scenarios).
    Enum: "MANUAL_REVIEW", "CUSTOMER_COMPLAINTS", "CHARGEBACKS", "OTHER_VENDORS", "AUTOMATED_DETECTION", "LAW_ENFORCEMENT"

  - `label.label_timestamp` (number)
    Unix time indicating the label creation time
    Example: 1725961384920

  - `afftectedActionIds` (array, required)
    Example: ["af819f2b3e2f1b2820077cb09fe92de5769c4e4b24030cf683f4d0b155ac4999","9b83568185c39e4acb3e5d09176f0a70efdf5c414c2d1d90cb803dfb0b93ec53"]

## Response 400:

  - `400` (unknown)
    Bad request

## Response 401:

  - `401` (unknown)
    Invalid authentication

## Response 403:

  - `403` (unknown)
    Invalid authorization

## Response 429:

  - `429` (unknown)
    Rate limit reached

## Response 500:

  - `500` (unknown)
    Internal error

