Skip to main content
Documentation Powered by Redocly

Ntropy Transaction API

API Support: api@ntropy.com URL: https://ntropy.com/developers

The world's most powerful, multi-geo, multi-lingual transaction categorization API.

Authentication

ApiKeyAuth

Security Scheme Type API Key
Header parameter name: X-API-KEY

Enrichment

Transaction enrichment.

Enrich and add transactions to the ledger of account holders synchronously.

Add transactions to the ledgers of account holders and get back enriched version of the transactions in the response. Accepts batch sizes up to 4k transactions. A single transaction should take ~100ms. A batch of 4000 transactions should take ~40s.

Authorizations:
ApiKeyAuth
    query Parameters
    model_name
    string

    If provided, the transaction enrichment will use the referenced custom model for labelling

    Request Body schema: application/json
    Array (<= 4000 items)
    transaction_id
    required
    string non-empty

    A unique identifier of the transaction

    account_holder_id
    string or null non-empty

    The unique ID of the account holder of the transaction

    account_holder_type
    string or null
    Enum: "consumer" "business" "freelance" "unknown"

    The type of an account holder, may be one of 'consumer', 'business', 'freelance' or 'unknown'.

    amount
    required
    number >= 0

    The amount of the transaction

    entry_type
    required
    string
    Enum: "incoming" "outgoing"

    The direction of the transaction (incoming or outgoing)

    date
    required
    string or null <date>

    The date that the transaction was posted. Uses ISO 8601 format (YYYY-MM-DD)

    iso_currency_code
    required
    string <currency>

    The currency of the transaction in ISO 4217 format

    description
    required
    string [ 0 .. 1024 ] characters

    The description string of the transaction

    country
    string[A-Z]{2}(-[A-Z0-9]{1,3})?

    The country where the transaction was made in ISO 3166-2 format

    mcc
    number [ 700 .. 9999 ]

    The Merchant Category Code of the merchant according to ISO 18245

    Responses

    Request samples

    Content type
    application/json
    [
    • {
      }
    ]

    Response samples

    Content type
    application/json
    [
    • {
      }
    ]

    Enrich and add transactions to the ledgers of account holders asynchronously.

    Add a batch of transactions to the ledgers of account holders. Return the batch id that has been assigned to this batch. A batch of 24960 transactions should take 5-10mins.

    Authorizations:
    ApiKeyAuth
      query Parameters
      model_name
      string

      If provided, the transaction enrichment will use the referenced custom model for labelling

      Request Body schema: application/json
      Array (<= 24960 items)
      transaction_id
      required
      string non-empty

      A unique identifier of the transaction

      account_holder_id
      string or null non-empty

      The unique ID of the account holder of the transaction

      account_holder_type
      string or null
      Enum: "consumer" "business" "freelance" "unknown"

      The type of an account holder, may be one of 'consumer', 'business', 'freelance' or 'unknown'.

      amount
      required
      number >= 0

      The amount of the transaction

      entry_type
      required
      string
      Enum: "incoming" "outgoing"

      The direction of the transaction (incoming or outgoing)

      date
      required
      string or null <date>

      The date that the transaction was posted. Uses ISO 8601 format (YYYY-MM-DD)

      iso_currency_code
      required
      string <currency>

      The currency of the transaction in ISO 4217 format

      description
      required
      string [ 0 .. 1024 ] characters

      The description string of the transaction

      country
      string[A-Z]{2}(-[A-Z0-9]{1,3})?

      The country where the transaction was made in ISO 3166-2 format

      mcc
      number [ 700 .. 9999 ]

      The Merchant Category Code of the merchant according to ISO 18245

      Responses

      Request samples

      Content type
      application/json
      [
      • {
        }
      ]

      Response samples

      Content type
      application/json
      {
      • "status": "started",
      • "updated_at": "2019-11-30 18:32:28+00:00",
      • "progress": 88,
      • "id": "247ee045-3d04-4b3c-872b-a9160b810f33"
      }

      Fetch the result of a batch transaction enrichment.

      Get a result of batch transaction enrichments. The id field should be as returned by /v2/transactions/async.

      Authorizations:
      ApiKeyAuth
        path Parameters
        id
        required
        string <uuid> 36 characters
        Example: 247ee045-3d04-4b3c-872b-a9160b810f33

        Batch id.

        Responses

        Request samples 

        curl -X "GET" \
  "https://api.ntropy.com/v2/transactions/async/{batch_id}" \
  -H "accept: application/json" \
  -H "X-API-KEY: $NTROPY_API_KEY"

        Response samples

        Content type
        application/json
        {
        • "status": "finished",
        • "updated_at": "2019-11-30 18:32:28+00:00",
        • "progress": 88,
        • "id": "247ee045-3d04-4b3c-872b-a9160b810f33",
        • "results": [
          ]
        }

        Account Holder

        Ledger operations.

        Retrieve the information of an account holder.

        Retrieve the stored information for an account holder.

        Authorizations:
        ApiKeyAuth
          path Parameters
          account_holder_id
          required
          string
          Example: 247ee045-3d04-4b3c-872b-a9160b810f33

          Responses

          Request samples 

          curl -X "GET" \
  "https://api.ntropy.com/v2/account-holder/{account_holder_id}" \
  -H "accept: application/json" \
  -H "X-API-KEY: $NTROPY_API_KEY"

          Response samples

          Content type
          application/json
          {
          • "id": "67890",
          • "type": "business",
          • "name": "Ntropy Network Inc.",
          • "industry": "fintech",
          • "website": "ntropy.com"
          }

          List transactions of an account holder.

          Fetch all the transactions in the transaction ledger of an account holder.

          Authorizations:
          ApiKeyAuth
            path Parameters
            account_holder_id
            required
            string
            Example: 247ee045-3d04-4b3c-872b-a9160b810f33
            query Parameters
            page
            integer
            Default: 0

            What page to start from.

            per_page
            integer [ 1 .. 10000 ]
            Default: 1000

            Number of results per page.

            Responses

            Request samples 

            curl -X "GET" \
  "https://api.ntropy.com/v2/account-holder/{account_holder_id}/transactions?page=0&per_page=1000" \
  -H "accept: application/json" \
  -H "X-API-KEY: $NTROPY_API_KEY"

            Response samples

            Content type
            application/json
            {
            • "transactions": [
              ],
            • "pages": 0
            }

            Get transactions of an account holder by transaction id.

            Fetch all the transactions matching given transaction ids in the transaction ledger of an account holder. Transactions returned will be in arbitrary order.

            Authorizations:
            ApiKeyAuth
              path Parameters
              account_holder_id
              required
              string
              Example: 247ee045-3d04-4b3c-872b-a9160b810f33
              Request Body schema: application/json
              Array
              string <= 5000 characters

              Responses

              Request samples

              Content type
              application/json
              [
              • "string"
              ]

              Response samples

              Content type
              application/json
              {
              • "transactions": [
                ]
              }

              Query the transaction ledger of an account holder.

              Submit a query to the transaction ledger of an account holder.

              Authorizations:
              ApiKeyAuth
                path Parameters
                account_holder_id
                required
                string
                Example: 247ee045-3d04-4b3c-872b-a9160b810f33
                Request Body schema: application/json
                metrics
                Array of strings (AccountHolderMetricName)
                Items Enum: "overall_stats" "stats_by_label" "stats_by_merchant"
                start
                string (DateOrDateTime)
                end
                string (DateOrDateTime)
                property name*
                any

                Responses

                Request samples

                Content type
                application/json
                {
                • "metrics": [
                  ],
                • "start": "2022-01-01 00:00:00",
                • "end": "2022-02-01 00:00:00"
                }

                Response samples

                Content type
                application/json
                {
                • "overall_stats": {
                  },
                • "stats_by_label": {
                  },
                • "stats_by_merchant": {
                  }
                }

                Categorize an account holder's histories income by their frequency and type

                Given the history of transactions of an account holder, determines income sources based on grouping transactions by income groups accounting for their amounts, frequency, source and other properties. The information returned is a summary of all income groups for this account holder.

                Authorizations:
                ApiKeyAuth
                  path Parameters
                  account_holder_id
                  required
                  string
                  Example: 247ee045-3d04-4b3c-872b-a9160b810f33

                  Responses

                  Response samples

                  Content type
                  application/json
                  [
                  • {
                    }
                  ]

                  Identify existing recurring payments for an account holder's transaction history.

                  Given the history of transactions of an account holder, determines existing recurring payments and related properties such as the type (subscription or bill), amount, periodicity, etc...

                  Authorizations:
                  ApiKeyAuth
                    path Parameters
                    account_holder_id
                    required
                    string
                    Example: 247ee045-3d04-4b3c-872b-a9160b810f33

                    Responses

                    Response samples

                    Content type
                    application/json
                    [
                    • {
                      }
                    ]

                    Misc

                    Other.

                    Report a wrongly classified transaction.

                    Report a wrongly classified transaction specifying expected enrichment values.

                    Authorizations:
                    ApiKeyAuth
                      Request Body schema: application/json
                      transaction_id
                      required
                      string
                      logo
                      string or null
                      website
                      string or null
                      location
                      string or null
                      merchant
                      string or null
                      merchant_id
                      string or null
                      labels
                      Array of strings or null
                      person
                      string or null
                      recurrence
                      string or null
                      recurrence_group_id
                      string or null
                      mcc
                      Array of integers or null
                      notes
                      string or null
                      webhook_url
                      string or null
                      property name*
                      any

                      Responses

                      Request samples

                      Content type
                      application/json
                      {
                      • "transaction_id": "xbx8YP14g565Xketw3tFmn4yp49x3tbj9mD8DB4fM8DDY6x",
                      • "website": "www.expected.website",
                      • "merchant": "Other Merchant"
                      }

                      Response samples

                      Content type
                      application/json
                      {
                      • "status": "string",
                      • "id": "string",
                      • "created_at": "2019-08-24",
                      • "transaction_id": "string",
                      • "webhook_url": "string"
                      }

                      List all submited reports (paginated and filterable).

                      Given a page size and page number, lists a specific page of previously submitted reports, optionally filtered by status and transaction_id.

                      Authorizations:
                      ApiKeyAuth
                        query Parameters
                        per_page
                        integer [ 1 .. 10000 ]
                        Default: 1000

                        Number of results per page.

                        page
                        integer
                        Default: 0

                        What page to start from.

                        status
                        string

                        Report status to filter by.

                        transaction_id
                        string

                        Report transaction_id to filter by.

                        Responses

                        Response samples

                        Content type
                        application/json
                        {
                        • "pages": 0,
                        • "reports": [
                          ]
                        }

                        Returns a report by id

                        Returns all the available information about a previously submitted report by it's identifier.

                        Authorizations:
                        ApiKeyAuth
                          path Parameters
                          id
                          required
                          string <uuid> 36 characters
                          Example: 247ee045-3d04-4b3c-872b-a9160b810f33

                          Report id.

                          Responses

                          Response samples

                          Content type
                          application/json
                          {
                          • "status": "string",
                          • "id": "string",
                          • "created_at": "2019-08-24",
                          • "transaction_id": "string",
                          • "webhook_url": "string"
                          }

                          Get the hierarchy of Ntropy labels

                          Get the hierarchy of Ntropy labels

                          Authorizations:
                          ApiKeyAuth
                            None
                            path Parameters
                            account_holder_type
                            required
                            string (AccountHolderType)
                            Enum: "consumer" "business" "freelance" "unknown"

                            The type of the transaction account holder (consumer, business, or freelance)

                            Responses

                            Request samples 

                            curl -X "GET" \
  "https://api.ntropy.com/v2/labels/hierarchy/consumer" \
  -H "accept: application/json"

                            Response samples

                            Content type
                            application/json
                            {
                            • "professional services": [
                              ],
                            • "infrastructure": [
                              ],
                            • "fees": [
                              ],
                            • "employees": {
                              },
                            • "insurance": [ ]
                            }

                            Get the current personalization ruleset.

                            Get the current personalization ruleset.

                            Authorizations:
                            ApiKeyAuth

                              Responses

                              Response samples

                              Content type
                              application/json
                              [
                              • {
                                }
                              ]

                              Set the personalization ruleset.

                              Set the personalization ruleset.

                              Authorizations:
                              ApiKeyAuth
                                Request Body schema: application/json
                                Array
                                Any of
                                required
                                boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
                                Array of any (action) [ items ]
                                Array of any (action) [ items ]

                                Responses

                                Request samples

                                Content type
                                application/json
                                [
                                • {
                                  }
                                ]

                                Delete a rule.

                                Delete the rule at the specified index from the personalization ruleset.

                                Authorizations:
                                ApiKeyAuth
                                  path Parameters
                                  index
                                  required
                                  integer

                                  Responses

                                  Request samples 

                                  curl -X "DELETE" \
  "https://api.ntropy.com/v2/rules/0" \
  -H "accept: */*" \
  -H "X-API-KEY: $NTROPY_API_KEY" \

                                  Replace a rule.

                                  Replace the rule at the specified index in the personalization ruleset.

                                  Authorizations:
                                  ApiKeyAuth
                                    path Parameters
                                    index
                                    required
                                    integer
                                    Request Body schema: application/json
                                    Any of
                                    required
                                    boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
                                    Array of any (action) [ items ]
                                    Array of any (action) [ items ]

                                    Responses

                                    Request samples

                                    Content type
                                    application/json
                                    Example
                                    if
                                    if
                                    modify labels
                                    set
                                    {
                                    • "if": true,
                                    • "then": [
                                      ],
                                    • "else": [
                                      ]
                                    }

                                    Append a rule.

                                    Append a rule to the personalization ruleset.

                                    Authorizations:
                                    ApiKeyAuth
                                      Request Body schema: application/json
                                      Any of
                                      required
                                      boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
                                      Array of any (action) [ items ]
                                      Array of any (action) [ items ]

                                      Responses

                                      Request samples

                                      Content type
                                      application/json
                                      Example
                                      if
                                      if
                                      modify labels
                                      set
                                      {
                                      • "if": true,
                                      • "then": [
                                        ],
                                      • "else": [
                                        ]
                                      }

                                      Get an account holder's personalization ruleset.

                                      Get an account holder's personalization ruleset.

                                      Authorizations:
                                      ApiKeyAuth
                                        path Parameters
                                        account_holder_id
                                        required
                                        string
                                        Example: 247ee045-3d04-4b3c-872b-a9160b810f33

                                        Responses

                                        Response samples

                                        Content type
                                        application/json
                                        [
                                        • {
                                          }
                                        ]

                                        Set an account holder's personalization ruleset.

                                        Set an account holder's personalization ruleset.

                                        Authorizations:
                                        ApiKeyAuth
                                          path Parameters
                                          account_holder_id
                                          required
                                          string
                                          Example: 247ee045-3d04-4b3c-872b-a9160b810f33
                                          Request Body schema: application/json
                                          Array
                                          Any of
                                          required
                                          boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
                                          Array of any (action) [ items ]
                                          Array of any (action) [ items ]

                                          Responses

                                          Request samples

                                          Content type
                                          application/json
                                          [
                                          • {
                                            }
                                          ]

                                          Append a rule.

                                          Append a rule to an account holder's personalization ruleset.

                                          Authorizations:
                                          ApiKeyAuth
                                            path Parameters
                                            account_holder_id
                                            required
                                            string
                                            Example: 247ee045-3d04-4b3c-872b-a9160b810f33
                                            Request Body schema: application/json
                                            Any of
                                            required
                                            boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
                                            Array of any (action) [ items ]
                                            Array of any (action) [ items ]

                                            Responses

                                            Request samples

                                            Content type
                                            application/json
                                            Example
                                            if
                                            if
                                            modify labels
                                            set
                                            {
                                            • "if": true,
                                            • "then": [
                                              ],
                                            • "else": [
                                              ]
                                            }

                                            Delete a rule

                                            Delete the rule at the specified index from an account holder's personalization ruleset.

                                            Authorizations:
                                            ApiKeyAuth
                                              path Parameters
                                              account_holder_id
                                              required
                                              string
                                              Example: 247ee045-3d04-4b3c-872b-a9160b810f33
                                              index
                                              required
                                              integer

                                              Responses

                                              Request samples 

                                              curl -X "DELETE" \
  "https://api.ntropy.com/v2/rules/0" \
  -H "accept: */*" \
  -H "X-API-KEY: $NTROPY_API_KEY" \

                                              Replace a rule

                                              Replace the rule at the specified index in an account holder's personalization ruleset.

                                              Authorizations:
                                              ApiKeyAuth
                                                path Parameters
                                                account_holder_id
                                                required
                                                string
                                                Example: 247ee045-3d04-4b3c-872b-a9160b810f33
                                                index
                                                required
                                                integer
                                                Request Body schema: application/json
                                                Any of
                                                required
                                                boolean (boolean) or string (string) or number (number) or (function (&& (object) or || (object) or == (object) or + (object) or - (object) or * (object) or / (object) or // (object) or < (object) or <= (object) or > (object) or >= (object) or ! (object) or is_substring (object) or to_lower (object) or to_upper (object) or has_label (object) or has_mcc (object) or get property (object))) (expression)
                                                Array of any (action) [ items ]
                                                Array of any (action) [ items ]

                                                Responses

                                                Request samples

                                                Content type
                                                application/json
                                                Example
                                                if
                                                if
                                                modify labels
                                                set
                                                {
                                                • "if": true,
                                                • "then": [
                                                  ],
                                                • "else": [
                                                  ]
                                                }

                                                Check API health.

                                                Get the API health info.

                                                Responses

                                                Request samples 

                                                curl -X "GET" \
  "https://api.ntropy.com/health" \
  -H "accept: */*"

                                                Response samples

                                                Content type
                                                application/json
                                                {
                                                • "status": "ok",
                                                • "updated_at": 1655476329.8150651
                                                }

                                                Bank statements

                                                Submit and view bank statements.

                                                Retrieves paginated information of multiple bank statements

                                                Authorizations:
                                                ApiKeyAuth
                                                  query Parameters
                                                  status
                                                  string (DocumentStatus)
                                                  Enum: "queued" "processing" "processed" "failed"

                                                  An enumeration.

                                                  page
                                                  integer (Page) >= 0
                                                  Default: 0
                                                  page_size
                                                  integer (Page Size) [ 1 .. 1000 ]
                                                  Default: 20
                                                  order_by
                                                  string (Order By)
                                                  Default: "desc"
                                                  Enum: "desc" "asc"

                                                  Responses

                                                  Response samples

                                                  Content type
                                                  application/json
                                                  [
                                                  • {
                                                    }
                                                  ]

                                                  Submit a bank statement

                                                  Authorizations:
                                                  ApiKeyAuth
                                                    Request Body schema: multipart/form-data
                                                    file
                                                    required
                                                    string <binary> (File)

                                                    Responses

                                                    Response samples

                                                    Content type
                                                    application/json
                                                    {
                                                    • "doc_type": "payslip",
                                                    • "id": "string",
                                                    • "user_id": 0,
                                                    • "filename": "string",
                                                    • "created_at": "2019-08-24T14:15:22Z"
                                                    }

                                                    Retrieve information of a bank statement

                                                    Authorizations:
                                                    ApiKeyAuth
                                                      path Parameters
                                                      uuid
                                                      required
                                                      string (Uuid)

                                                      Responses

                                                      Response samples

                                                      Content type
                                                      application/json
                                                      {
                                                      • "id": "string",
                                                      • "uuid": "string",
                                                      • "fname": "string",
                                                      • "status": "string",
                                                      • "created_at": "2019-08-24T14:15:22Z",
                                                      • "transactions": [
                                                        ],
                                                      • "error_code": 0,
                                                      • "error": "string"
                                                      }

                                                      Custom Models

                                                      Get all available custom labelling models.

                                                      Authorizations:
                                                      ApiKeyAuth

                                                        Responses

                                                        Request samples 

                                                        curl -X "GET" \
  "https://api.ntropy.com/v2/models" \
  -H "accept: application/json" \
  -H "X-API-KEY: $NTROPY_API_KEY"

                                                        Response samples

                                                        Content type
                                                        application/json
                                                        [
                                                        • {
                                                          }
                                                        ]

                                                        Train a custom labelling model with unique name.

                                                        Using a set of pre-labeled transactions, trains a custom labelling model that is tuned in the provided dataset and associated with an unique name. To use the trained model for labeling, use the model_name parameter of the /transactions/sync or /transactions/async API call parameter of the /transactions/sync or /transactions/async API call.

                                                        Authorizations:
                                                        ApiKeyAuth
                                                          path Parameters
                                                          name
                                                          required
                                                          string
                                                          Example: my-model-name

                                                          Model name.

                                                          Request Body schema: application/json
                                                          required
                                                          Array of objects (LabelledTransaction) [ 1 .. 50000 ] items [ items ]
                                                          property name*
                                                          any

                                                          Responses

                                                          Request samples

                                                          Content type
                                                          application/json
                                                          {
                                                          • "transactions": [
                                                            ]
                                                          }

                                                          Response samples

                                                          Content type
                                                          application/json
                                                          {
                                                          • "name": "string",
                                                          • "progress": 0,
                                                          • "status": "string"
                                                          }

                                                          Get requested model status.

                                                          Get requested model status identified by name

                                                          Authorizations:
                                                          ApiKeyAuth
                                                            path Parameters
                                                            name
                                                            required
                                                            string
                                                            Example: my-model-name

                                                            Model name.

                                                            Responses

                                                            Request samples 

                                                            curl -X "GET" \
  "https://api.ntropy.com/v2/models/{name}" \
  -H "accept: application/json" \
  -H "X-API-KEY: $NTROPY_API_KEY"

                                                            Response samples

                                                            Content type
                                                            application/json
                                                            {
                                                            • "name": "string",
                                                            • "progress": 0,
                                                            • "status": "string"
                                                            }