Logo

Subusers

Subusers, or customers, are where your users live in Evomi — they are a collection of your customers. You will need one subuser for each of your customers. Each subuser can have access to one or many different products.

PUT/v2/reseller/sub_users/create

Create subuser

This endpoint allows you to create a new customer. It is not allowed to create a subuser for each registered user on your website. Please only create subusers for your customers once they actually purchase!

Required Body "Raw" Items

  • Name
    username
    Type
    string
    Description

    The username of the customer.

  • Name
    email
    Type
    string
    Description

    The email address of the customer.

Returned Properties

  • Name
    data
    Type
    object
    Description

    The account data of the customer. This includes the email, username, aswell as the products. Each product has its own proxy_key. While some products operate on a balance others are limited by time and threads.

  • Name
    message
    Type
    string
    Description

    The message of the response.

  • Name
    status
    Type
    number
    Description

    The status code of the response.

  • Name
    timestamp
    Type
    number
    Description

    The timestamp in milliseconds of the response.

Request

PUT
/v2/reseller/sub_users/create
  curl --location --request PUT 'https://reseller.evomi.com/v2/reseller/sub_users/create' \
    --header 'X-API-KEY: [API KEY]' \
    --data '{"username":"Evomi_customer","email":"[email protected]"}'

Response

{
"message": "",
"timestamp": 1710521742499,
"data": {
    "email": "[email protected]",
    "username": "Evomi_customer",
    "created_at": "2024-03-15T16:55:42.493283Z",
    "updated_at": "2024-03-15T16:55:42.493283Z",
    "products": {
        "residential": {
            "balance": 0,
            "proxy_key": "o3ES790NowLodxOuFNup"
        },
        "sharedDataCenter": {
            "balance": 0,
            "proxy_key": "NudAMGhkISx6skP65dQx"
        },
        "dataCenterIPV6": {
            "proxy_key": "wvmL818vcseyNBIx0P3d",
            "threadCap": 0,
            "expiresAt": "0001-01-01T00:00:00Z",
            "expiresInHours": -2562047.788015,
            "balance": 0
        },
        "mobile": {
            "balance": 0,
            "proxy_key": "vxHEmIRGWWoiegbscLQV"
        },
        "dataCenter": {
            "proxy_key": "oZraZtsV2Lz7CCmVl4cf",
            "threadCap": 0,
            "expiresAt": "0001-01-01T00:00:00Z",
            "expiresInHours": -2562047.788015,
            "balance": 0
        }
    }
},
"status": 201
}
GET/v2/reseller/sub_users/view_all

List all subusers

This endpoint allows you to retrieve a list of all your subusers.

Returned Properties

  • Name
    data
    Type
    object
    Description

    The list of your subusers.

  • Name
    message
    Type
    string
    Description

    The message of the response.

  • Name
    status
    Type
    number
    Description

    The status code of the response.

  • Name
    timestamp
    Type
    number
    Description

    The timestamp in milliseconds of the response.

Request

GET
/v2/reseller/sub_users/view_all
  curl -G 'https://reseller.evomi.com/v2/reseller/sub_users/view_all' \
  --header 'X-API-KEY: [API KEY]'

Response

{
"data": [
    {
        "email": "[email protected]",
        "username": "Evomi_customer",
        "created_at": "2023-05-24T06:24:20.659042Z",
        "updated_at": "2024-02-22T17:29:32.254288Z",
        "products": {
            "mobile": {
                "balance": 0,
                "proxy_key": "FYU0P5F1E8MWD9CvW763"
            },
            "residentialIPV6": {
                "proxy_key": "wyBEkR1d4ycMk05P5M1I",
                "threadCap": 0,
                "expiresAt": "2024-01-23T12:22:44.272889Z",
                "expiresInHours": -1252.610291,
                "balance": 0
            },
            "dataCenter": {
                "proxy_key": "E4grDGiuh22uglZvh5W3",
                "threadCap": 0,
                "expiresAt": "2024-03-13T10:50:23.60576Z",
                "expiresInHours": -54.149366,
                "balance": 0
            },
            "residential": {
                "balance": 2,
                "proxy_key": "R86iEzvmQYHbO6q4bUWB"
            },
            "sharedDataCenter": {
                "balance": 0,
                "proxy_key": "oQ85ySTYABJ7XuI02op5"
            },
            "dataCenterIPV6": {
                "proxy_key": "PHYFHFk5kCY7tWO0O1Zm",
                "threadCap": 0,
                "expiresAt": "2024-01-29T14:15:09.111242Z",
                "expiresInHours": -1106.736725,
                "balance": 0
            }
        }
    },
   ...
   
    
],
"status": 200,
"message": "",
"timestamp": 1710521961322
}
GET/v2/reseller/sub_users/view_single?username={username}

Get single subuser

This endpoint allows you to retrieve a single subuser by providing the subuser's username. Refer to the list at the top of this page to see which properties are included with customer objects.

Required query parameters

  • Name
    username
    Type
    string
    Description

    The username of the customer you want to retrieve.

Returned Properties

  • Name
    data
    Type
    object
    Description

    The account data of the subuser.

  • Name
    message
    Type
    string
    Description

    The message of the response.

  • Name
    status
    Type
    number
    Description

    The status code of the response.

  • Name
    timestamp
    Type
    number
    Description

    The timestamp in milliseconds of the response.

Request

GET
/v2/reseller/sub_users/view_single?username=Evomi_customer
  curl -G 'https://reseller.evomi.com/v2/reseller/sub_users/view_single?username=Evomi_customer' \
  --header 'X-API-KEY: [API KEY]'

Response

{
"message": "",
"timestamp": 1710521742499,
"data": {
    "email": "[email protected]",
    "username": "Evomi_customer",
    "created_at": "2024-03-15T16:55:42.493283Z",
    "updated_at": "2024-03-15T16:55:42.493283Z",
    "products": {
        "residential": {
            "balance": 0,
            "proxy_key": "o3ES790NowLodxOuFNup"
        },
        "sharedDataCenter": {
            "balance": 0,
            "proxy_key": "NudAMGhkISx6skP65dQx"
        },
        "dataCenterIPV6": {
            "proxy_key": "wvmL818vcseyNBIx0P3d",
            "threadCap": 0,
            "expiresAt": "0001-01-01T00:00:00Z",
            "expiresInHours": -2562047.788015,
            "balance": 0
        },
        "mobile": {
            "balance": 0,
            "proxy_key": "vxHEmIRGWWoiegbscLQV"
        },
        "dataCenter": {
            "proxy_key": "oZraZtsV2Lz7CCmVl4cf",
            "threadCap": 0,
            "expiresAt": "0001-01-01T00:00:00Z",
            "expiresInHours": -2562047.788015,
            "balance": 0
        }
    }
},
"status": 201
}
GET/v2/reseller/sub_users/view_txs?username=Evomi_customer&duration=24h&granularity=minute

Get Usage History

This endpoint allows you to retrieve the consumptions of a subuser.

Required parameters

  • Name
    username
    Type
    string
    Description

    The username of the customer you want to retrieve.

  • Name
    duration
    Type
    string
    Description

    The duration of the consumptions you want to retrieve.
    Can be in d or h (days or hours).

  • Name
    granularity
    Type
    string
    Description

    The granularity of the consumptions you want to retrieve.
    Can be minute, hour or day.

Returned Properties

  • Name
    data
    Type
    object
    Description

    The data of consumptions based on the duration and granularity you provided.

  • Name
    message
    Type
    string
    Description

    The message of the response.

  • Name
    status
    Type
    number
    Description

    The status code of the response.

  • Name
    timestamp
    Type
    number
    Description

    The timestamp in milliseconds of the response.

Request

GET
/v2/reseller/sub_users/view_txs?username=Evomi_customer&duration=24h&granularity=hour
  curl -G 'https://reseller.evomi.com/v2/reseller/sub_users/view_txs?username=Evomi_customer&duration=24h&granularity=hour' \
  --header 'X-API-KEY: [API KEY]'

Response

{
"status": 200,
"message": "",
"timestamp": 1710595239055,
"data": {
    "products": [
        {
            "name": "Residential",
            "totalBandwidth": 0,
            "stats": {
                "2024-03-03 00:00": 0,
                "2024-03-04 00:00": 0,
                "2024-03-05 00:00": 0,
                "2024-03-06 00:00": 0,
                "2024-03-07 00:00": 0,
                "2024-03-08 00:00": 0,
                "2024-03-09 00:00": 0,
                "2024-03-10 00:00": 0,
                "2024-03-11 00:00": 0,
                "2024-03-12 00:00": 0,
                "2024-03-13 00:00": 0,
                "2024-03-14 00:00": 0,
                "2024-03-15 00:00": 0,
                "2024-03-16 00:00": 0
            }
        },
        {
            "name": "Shared Data Center",
            "totalBandwidth": 0,
            "stats": {
                "2024-03-03 00:00": 0,
                "2024-03-04 00:00": 0,
                "2024-03-05 00:00": 0,
                "2024-03-06 00:00": 0,
                "2024-03-07 00:00": 0,
                "2024-03-08 00:00": 0,
                "2024-03-09 00:00": 0,
                "2024-03-10 00:00": 0,
                "2024-03-11 00:00": 0,
                "2024-03-12 00:00": 0,
                "2024-03-13 00:00": 0,
                "2024-03-14 00:00": 0,
                "2024-03-15 00:00": 0,
                "2024-03-16 00:00": 0
            }
        },
        {
            "name": "Mobile",
            "totalBandwidth": 0,
            "stats": {
                "2024-03-03 00:00": 0,
                "2024-03-04 00:00": 0,
                "2024-03-05 00:00": 0,
                "2024-03-06 00:00": 0,
                "2024-03-07 00:00": 0,
                "2024-03-08 00:00": 0,
                "2024-03-09 00:00": 0,
                "2024-03-10 00:00": 0,
                "2024-03-11 00:00": 0,
                "2024-03-12 00:00": 0,
                "2024-03-13 00:00": 0,
                "2024-03-14 00:00": 0,
                "2024-03-15 00:00": 0,
                "2024-03-16 00:00": 0
            }
        }
    ]
}
}
GET/v2/reseller/view_domain_stats?username=Evomi_customer&product=rp&granularity=hour&duration=12h

Get Domain Stats

This endpoint allows you to retrieve the request statistics of a subuser, including the domains they connected to and the request counts per time bucket.

Required parameters

  • Name
    username
    Type
    string
    Description

    The username of the customer you want to retrieve.

  • Name
    product
    Type
    string
    Description

    The product you want to retrieve the statistics for.
    Can be rp (Residential), sdc (Shared Data Center) or mp (Mobile).

  • Name
    granularity
    Type
    string
    Description

    The granularity of the statistics you want to retrieve.
    Can be minute, hour or day.

  • Name
    duration
    Type
    string
    Description

    The duration of the statistics you want to retrieve.
    Can be in m, h or d (minutes, hours or days). The maximum duration is 13h.

Returned Properties

  • Name
    data
    Type
    object
    Description

    Contains dates, a map of time buckets to request counts, and domains, a map of the domains the subuser connected to with their request counts and bandwidth usage. Results may be cached for up to 10 minutes.

  • Name
    message
    Type
    string
    Description

    The message of the response.

  • Name
    status
    Type
    number
    Description

    The status code of the response.

  • Name
    timestamp
    Type
    number
    Description

    The timestamp in milliseconds of the response.

Request

GET
/v2/reseller/view_domain_stats?username=Evomi_customer&product=rp&granularity=hour&duration=12h
  curl -G 'https://reseller.evomi.com/v2/reseller/view_domain_stats?username=Evomi_customer&product=rp&granularity=hour&duration=12h' \
  --header 'X-API-KEY: [API KEY]'

Response

{
"status": 200,
"message": "",
"timestamp": 1710595239055,
"data": {
    "dates": {
        "2024-03-16 09:00": 120,
        "2024-03-16 10:00": 85,
        "2024-03-16 11:00": 143
    },
    "domains": {
        "example.com": {
            "request_count": 250,
            "total_bandwidth_used": 10485
        },
        "api.example.org": {
            "request_count": 98,
            "total_bandwidth_used": 3211
        }
    }
}
}
POST/v2/reseller/sub_users/delete_session?username=Evomi_customer&session=examplesession

Delete proxy session

This endpoint allows you to delete an active proxy session of a subuser. This is useful if you want to force a session to be re-assigned to a new IP address.

Required parameters

  • Name
    username
    Type
    string
    Description

    The username of the customer whose session you want to delete.

  • Name
    session
    Type
    string
    Description

    The session identifier you want to delete.

Returned Properties

  • Name
    data
    Type
    object
    Description

    Contains success indicating whether the session was deleted.

  • Name
    message
    Type
    string
    Description

    The message of the response.

  • Name
    status
    Type
    number
    Description

    The status code of the response.

  • Name
    timestamp
    Type
    number
    Description

    The timestamp in milliseconds of the response.

Request

POST
/v2/reseller/sub_users/delete_session?username=Evomi_customer&session=examplesession
  curl -X POST 'https://reseller.evomi.com/v2/reseller/sub_users/delete_session?username=Evomi_customer&session=examplesession' \
  --header 'X-API-KEY: [API KEY]'

Response

{
"status": 200,
"message": "",
"timestamp": 1710595239055,
"data": {
    "success": true
}
}