MOmonta
Teams

Create a team

Changed on

Required scope: teams:write </br>Organization authorization: supported

post/api/v1/teams

Request

  • Base URL
    https://partner-api.monta.com
  • URL
    https://partner-api.monta.com/api/v1/teams
  • Auth
    HTTP bearer

Request body

userIdinteger nullable

Id of the user that owns the team.

userEmailstring email nullable

Email of the user that owns the team, useful when the userId is not known.

operatorIdinteger nullable

Id of the operator this team should be assigned to</br>Note: if not provided the team will be assigned to the default operator for the given consumer, if the default operator cannot be assigned the request will be rejected.

namestring required

Name of the team.

contactEmailstring email required

Contact email of the team. Named "email" in the GET APIs.

financeEmailstring email nullable

Finance contact email of the team.

financeCommunicationEmailstring email nullable

Recipient for important payment notices (late payment, freeze warning, frozen). When not set, these go to financeEmail.

legalEmailstring email nullable

Legal contact email of the team.

type'private' | 'professional' | 'operator' required
companyNamestring nullable

The company name for the team.

vatNumberstring nullable

The vat number for the team.

companyRegistrationNumberstring nullable

The company registration number for the team.

partnerExternalIdstring nullable

External Id of this entity, managed by you.</br>Deprecated: use customFields.externalId instead — both read and write the same value.

partnerCustomPayloadobject nullable

Custom JSON payload for this entity, managed by you.</br>Note: the expected shape is a flat JSON object with named keys. The payload is limited to 1000 characters.</br>Deprecated: use customFields instead; this payload is not migrated automatically.

customFieldsobject nullable

Custom fields to set on this entity: a flat map of string keys (1-64 characters, no : or ,, not starting with monta) to string values (up to 256 characters), at most 20 pairs per entity. Fields are scoped to your operator. externalId is the same value as the deprecated partnerExternalId.

paymentMethod'invoice' | 'operator_transaction' | 'source'
themeIdinteger nullable

The theme id to assign to the team.</br>Note: When theme is provided, it must belong to the same operator as the team

onboardingProfileIdinteger nullable

Onboarding profile to apply, from GET /onboarding-profiles. Copies the profile's steps onto the team and locks them to the profile. Cannot be combined with onboardingSteps.

categorystring nullable

Category identifier of the team, one of: housing-association, cpo, parking, hotel, fleet, company, priced-by-site-owner.</br>Note: if not provided Monta assigns a default based on the team type.

selfRegisterChargeKeysboolean nullable

Whether team members can register their own charge keys.</br>Note: defaults to false when omitted. Self-registration is also enabled when the team's operator team settings template enables it.

joinCodestring nullable

Custom code users enter in the app to join the team, 4-50 characters. Monta generates one when omitted.</br>Note: stored slugified (lowercased, spaces and symbols become dashes, e.g. MVV Energie 042 → mvv-energie-042); the response returns the stored value. Join codes are unique across all teams on Monta, so a code that is already taken (after slugifying) is rejected with 422.

Example request

{
  "userId": 42,
  "userEmail": "user@monta.com",
  "operatorId": 1,
  "name": "Monta CPH Team",
  "contactEmail": "contact@monta.com",
  "financeEmail": "finance_contact@monta.com",
  "financeCommunicationEmail": "billing_notices@monta.com",
  "legalEmail": "legal_contact@monta.com",
  "address": {
    "address1": "Strandboulevarden 122",
    "address2": "København",
    "address3": "5. sal",
    "city": "Berlin",
    "zipCode": "10011",
    "countryId": 194,
    "countryAreaId": 1
  },
  "companyName": "Monta ApS",
  "vatNumber": "DK13585628",
  "companyRegistrationNumber": "13585628",
  "partnerExternalId": "ACME-12345",
  "partnerCustomPayload": {
    "internalId": "ACME-12345",
    "department": "Fleet"
  },
  "customFields": {
    "externalId": "crm-4711",
    "costCenter": "DK-OPS-12"
  },
  "themeId": 721,
  "onboardingSteps": [
    {
      "step": "SETUP_CHARGING_RULE",
      "config": "scheduled",
      "displayMode": "full_screen"
    }
  ],
  "onboardingProfileId": 12,
  "onboardingWelcomeText": {
    "type": "home",
    "enabled": true
  },
  "category": "priced-by-site-owner",
  "selfRegisterChargeKeys": true,
  "joinCode": "mvv-energie-042"
}

Response

Team created

idinteger required

Id of the team

namestring required

Name of the team

emailstring nullable

Email of the team that will receive team communications. Named "contact email" in the creation/update APIs.

financeEmailstring nullable

Finance email of the team that will receive finance related emails

financeCommunicationEmailstring nullable

Recipient for important payment notices (late payment, freeze warning, frozen). When not set, these go to financeEmail.

legalEmailstring nullable

Legal email of the team (certified e-mail)

externalIdstring nullable

External id of the team

partnerExternalIdstring nullable

External Id of this entity, managed by you.</br>Deprecated: use customFields.externalId instead — both read and write the same value.

partnerCustomPayloadobject nullable

Custom JSON payload for this entity, managed by you.</br>Note: the expected shape is a flat JSON object with named keys.</br>Deprecated: use customFields instead; this payload is not migrated automatically.

customFieldsobject nullable

Custom fields of this entity, managed by you: a flat map of string keys (1-64 characters, no : or ,) to string values (up to 256 characters), at most 20 pairs. Fields are scoped to your operator and never visible to other operators. externalId is the same value as the deprecated partnerExternalId.

joinCodestring required

Code to share with a user to join the team. Slugified and unique across all teams on Monta.

recipientCodestring nullable

The recipient code used for e-invoicing

companyNamestring nullable

The company name for the given team

taxIdentificationNumberstring nullable

The tax identification number for the given team

vatNumberstring nullable

The VAT number for the given team

companyRegistrationNumberstring nullable

The company registration number for the team

type'private' | 'professional' | 'operator' required

Type of the team

operatorIdinteger nullable

Deprecated (will be removed by 01.04.24), use operator field instead.

userIdinteger required

Id of the user that owns this team

isFrozenboolean required

Whether the team is frozen or not

frozenReasonstring nullable

Team freezing reason

featureGroupIdinteger nullable

Feature group id assigned to team

frozenAtstring date-time nullable

Frozen date of this team

blockedAtstring date-time nullable

Blocked date of this team

createdAtstring date-time required

Creation date of this team

updatedAtstring date-time required

Update date of this team

deletedAtstring date-time nullable

The deleted date of this team

paymentMethod'invoice' | 'operator_transaction' | 'source' | 'unknown' required
themeIdinteger nullable

The theme id associated with the team.

autoWithdrawEnabledboolean

Whether automatic bank withdrawal is on for the team (equivalent to autoWithdrawNextAt being set). Mutually exclusive with invoiceWithdraw (see the team settings), but legacy teams can have both set, so check invoiceWithdraw as well.

autoWithdrawNextAtstring date-time nullable

When the next automatic withdrawal is due; null when automatic withdrawal is off. A payout only happens when the team also has a bank account, is not frozen and has enough balance.

hasPaymentCardboolean nullable

Whether this team has at least one saved card, including expired cards. Check paymentMethods[].expired to determine whether a saved card is still valid. Only returned on the single team read, and only when the consumer also has the wallet-transactions:read scope. Always null on team lists; null when the lookup failed.

Example response

{
  "id": 1,
  "name": "Internal team",
  "email": "email@it.com",
  "financeEmail": "email@it.com",
  "financeCommunicationEmail": "billing_notices@monta.com",
  "legalEmail": "email@it.com",
  "externalId": "123-ABC",
  "partnerExternalId": "ACME-12345",
  "partnerCustomPayload": {
    "internalId": "ACME-12345",
    "department": "Fleet"
  },
  "customFields": {
    "externalId": "crm-4711",
    "costCenter": "DK-OPS-12"
  },
  "joinCode": "mvv-energie-042",
  "recipientCode": "my-team-123",
  "companyName": "Housing XYZ",
  "taxIdentificationNumber": "123456789",
  "vatNumber": "DE123456789",
  "companyRegistrationNumber": "13585628",
  "operator": {
    "id": 14,
    "name": "Monta",
    "identifier": "monta",
    "partnerId": 1,
    "vatNumber": "FOO-123-ABC"
  },
  "address": {
    "address1": "Strandboulevarden 122",
    "address2": "København",
    "address3": "5. sal",
    "city": "Berlin",
    "province": "Lombardy",
    "countrySubdivisionCode": "US-GA",
    "zipCode": "10011",
    "countryId": 1
  },
  "currency": {
    "identifier": "dkk",
    "name": "Danish krone",
    "decimals": 2
  },
  "type": "personal",
  "category": {
    "identifier": "cpo",
    "name": "Charge Point Operator"
  },
  "operatorId": 1,
  "userId": 1,
  "frozenReason": "removed team",
  "featureGroupId": 1,
  "frozenAt": "2022-05-12T16:56:45.99Z",
  "blockedAt": "2022-05-12T15:56:45.99Z",
  "createdAt": "2022-05-12T15:56:45.99Z",
  "updatedAt": "2022-05-12T16:56:45.99Z",
  "deletedAt": "2022-05-12T16:56:45.99Z",
  "invoiceRequest": {
    "id": 12345,
    "status": "pending",
    "requestedAt": "2025-07-08T15:56:45.99Z",
    "approvedAt": "2025-07-08T16:00:00Z",
    "rejectedAt": "2025-07-08T16:05:00Z",
    "rejectionReason": "Missing required data",
    "updatedAt": "2025-07-08T16:10:00Z"
  },
  "themeId": 1,
  "tags": [
    {
      "id": 1,
      "name": "cpo"
    }
  ],
  "onboardingSteps": [
    {
      "step": "SETUP_CHARGING_RULE",
      "config": "scheduled",
      "displayMode": "full_screen"
    }
  ],
  "onboardingWelcomeText": {
    "type": "home",
    "enabled": true
  },
  "autoWithdrawEnabled": true,
  "autoWithdrawNextAt": "2026-11-01T00:00:00Z",
  "hasPaymentCard": true,
  "paymentMethods": [
    {
      "type": "card",
      "brand": "visa",
      "last4": "4242",
      "expiryMonth": 12,
      "expiryYear": 2028
    }
  ]
}

Changes

  • 0ca400461c52Revision changes
    • breaking

      the request property type changed from array to object

    • breaking

      the response's property type changed from array to object for status

    • warning

      added the new admin enum value to the // response property for the response status

    • warning

      added the new member enum value to the // response property for the response status

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property //

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      request property deprecated

    • info

      request property deprecated

    • info

      added the new admin enum value to the request property //

    • info

      added the new member enum value to the request property //

    • info

      added the non-success response with the status

    • info

      added the optional property ///// to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property // to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added the optional property to the response with the status

    • info

      added to the response property allOf list for the response status

    • info

      removed from the response property allOf list for the response status

    • info

      response property partnerCustomPayload deprecated

    • info

      response property partnerExternalId deprecated