API Docs

Table of contents

🔐 Auth
🧾 Transactions
- ✍️ Sign tx
- 📝 Sign message
👥 Users
🏤 Organizations
🏦 Plans
- 🛒 Get Available Plans
- 🛍️ Get Plan Info

🔐 Auth

🔑 Login

SDK method: This method is required by the Vocdoni SDK to use this service as a valid remote signer.

Path /auth/login
Method POST
Request Body

{
    "email": "my@email.me",
    "password": "secretpass1234"
}

Response

{
  "token": "<jwt_token>",
  "expirity": "2024-08-21T11:26:54.368718+02:00"
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40004`	`malformed JSON body`
`401`	`40014`	`user account not verified`
`500`	`50002`	`internal server error`

🥤 Refresh token

SDK method: This method is required by the Vocdoni SDK to use this service as a valid remote signer.

Path /auth/refresh
Method POST
Headers
- Authentication: Bearer <user_token>
Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`500`	`50002`	`internal server error`

💼 User writable organizations addresses

SDK method: This method is required by the Vocdoni SDK to use this service as a valid remote signer.

This endpoint only returns the addresses of the organizations where the current user (identified by the JWT) has a role with write permission.

Path /auth/addresses
Method GET
Headers
- Authentication: Bearer <user_token>
Response

{
  "addresses": [
    "0x0000000001",
    "0x0000000002",
    "0x0000000003",
  ]
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`404`	`40012`	`this user has not been assigned to any organization`
`500`	`50002`	`internal server error`

🧾 Transactions

✍️ Sign tx

SDK method: This method is required by the Vocdoni SDK to use this service as a valid remote signer.

Path /transactions
Method POST
Headers
- Authentication: Bearer <user_token>
Request body

{
  "address": "0x...",
  "txPayload": "<base64_encoded_protobuf>"
}

Response

{
  "txPayload": "<base64_encoded_protobuf>"
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40004`	`malformed JSON body`
`400`	`40006`	`could not sign transaction`
`400`	`40007`	`invalid transaction format`
`400`	`40008`	`transaction type not allowed`
`500`	`50002`	`internal server error`
`500`	`50003`	`could not create faucet package`

📝 Sign message

SDK method: This method is required by the Vocdoni SDK to use this service as a valid remote signer.

Path /transactions/message
Method POST
Headers
- Authentication: Bearer <user_token>
Request body

{
  "address": "0x...",
  "payload": "<payload_to_sign>"
}

Response

{
  "payload": "<payload_to_sign>"
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40004`	`malformed JSON body`
`500`	`50002`	`internal server error`

👥 Users

🙋 Register

Path /users
Method POST
Request body

{
    "email": "my@email.me",
    "firstName": "Steve",
    "lastName": "Urkel",
    "password": "secretpass1234"
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40002`	`email malformed`
`400`	`40003`	`password too short`
`400`	`40004`	`malformed JSON body`
`409`	`40901`	`duplicate conflict`
`500`	`50002`	`internal server error`

✅ Verify user

Path /users/verify
Method POST
Request Body

{
  "email": "user2veryfy@email.com",
  "code": "******",
}

Response

{
  "token": "<jwt_token>",
  "expirity": "2024-08-21T11:26:54.368718+02:00"
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40004`	`malformed JSON body`
`400`	`40005`	`invalid user data`
`400`	`40015`	`user account already verified`
`401`	`40016`	`verification code expired`
`500`	`50002`	`internal server error`

🪪 User verification code info

Path /users/verify/code
Method GET
Query params
- email
Response

{
  "email": "user@email.com",
  "expiration": "2024-09-20T09:02:26.849Z",
  "valid": true
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40005`	`invalid user data`
`400`	`40015`	`user account already verified`
`404`	`40018`	`user not found`
`500`	`50002`	`internal server error`

📤 Resend user verification code

Path /users/verify/code
Method POST
Request Body

{
  "email": "user@email.com",
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40004`	`malformed JSON body`
`400`	`40005`	`invalid user data`
`400`	`40015`	`user account already verified`
`400`	`40017`	`last verification code still valid`
`500`	`50002`	`internal server error`

🧑‍💻 Get current user info

Path /users/me
Method GET
Headers
- Authentication: Bearer <user_token>
Response

{
  "email": "test@test.test",
  "firstName": "Steve",
  "lastName": "Urkel",
  "organizations": [
    {
      "role": "admin",
      "organization": {
        "address": "0x...",
        "name": "Test Organization",
        "type": "community",
        "description": "My amazing testing organization",
        "size": 10,
        "color": "#ff0000",
        "logo": "https://[...].png",
        "subdomain": "mysubdomain",
        "timezone": "GMT+2",
        "active": true,
        "parent": {
            "...": "..."
        },
        "subscription":{
            "PlanID":3,
            "StartDate":"2024-11-07T15:25:49.218Z",
            "EndDate":"0001-01-01T00:00:00Z",
            "RenewalDate":"0001-01-01T00:00:00Z",
            "Active":true,
            "MaxCensusSize":10
        },
      }
    }
  ]
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`500`	`50002`	`internal server error`

💇 Update current user info

Path /users/me
Method PUT
Request body

{
    "email": "my@email.me",
    "firstName": "Steve",
    "lastName": "Urkel",
}

Response

This method invalidates any previous JWT token for the user, so it returns a new token to be used in following requests.

{
  "token": "<jwt_token>",
  "expirity": "2024-08-21T11:26:54.368718+02:00"
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40002`	`email malformed`
`400`	`40004`	`malformed JSON body`
`500`	`50002`	`internal server error`

🔏 Update current user password

Path /users/password
Method PUT
Request body

{
  "oldPassword": "secretpass1234",
  "newPassword": "secretpass0987"
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40003`	`password too short`
`400`	`40004`	`malformed JSON body`
`500`	`50002`	`internal server error`

⛓️‍💥 Request a password recovery

Path /users/password/recovery
Method POST
Request body

{
  "email": "user@test.com",
}

Errors

HTTP Status	Error code	Message
`400`	`40004`	`malformed JSON body`
`500`	`50002`	`internal server error`

🔗 Reset user password

Path /users/password/reset
Method POST
Request body

{
  "email": "user@test.com",
  "code": "******",
  "newPassword": "newpassword123"
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40003`	`password too short`
`400`	`40004`	`malformed JSON body`
`500`	`50002`	`internal server error`

🏤 Organizations

🆕 Create organization

Path /organizations
Method POST
Headers
- Authentication: Bearer <user_token>
Request body

{
  "name": "Test Organization",
  "website": "https://[...].com",
  "type": "community",
  "description": "My amazing testing organization",
  "size": "10",
  "color": "#ff0000",
  "logo": "https://[...].png",
  "header": "https://[...].png",
  "subdomain": "mysubdomain",
  "country": "Germany",
  "timezone": "GMT+2",
  "language": "EN"
}

By default, the organization is created with activated: true.

If the user want to create a sub org, the address of the root organization must be provided inside an organization object in parent param. The creator must be admin of the parent organization to be able to create suborganizations. Example:

{
    "parent": {
        "address": "0x..."
    }
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40004`	`malformed JSON body`
`400`	`40009`	`organization not found`
`400`	`40013`	`invalid organization data`
`500`	`50002`	`internal server error`

⚙️ Update organization

Path /organizations/{address}
Method PUT
Headers
- Authentication: Bearer <user_token>
Request body Only the following parameters can be changed. Every parameter is optional.

{
  "name": "Test Organization",
  "website": "https://[...].com",
  "type": "community",
  "description": "My amazing testing organization",
  "size": "10",
  "color": "#ff0000",
  "logo": "https://[...].png",
  "header": "https://[...].png",
  "subdomain": "mysubdomain",
  "country": "Germany",
  "timezone": "GMT+2",
  "Language": "EN",
  "active": true
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40004`	`malformed JSON body`
`400`	`40009`	`organization not found`
`400`	`40011`	`no organization provided`
`500`	`50002`	`internal server error`

🔍 Organization info

Path /organizations/{address}
Method GET
Response

{
  "address": "0x1234",
  "name": "Test Organization",
  "website": "https://[...].com",
  "type": "community",
  "description": "My amazing testing organization",
  "size": "10",
  "color": "#ff0000",
  "logo": "https://[...].png",
  "header": "https://[...].png",
  "subdomain": "mysubdomain",
  "country": "Germany",
  "timezone": "GMT+2",
  "Language": "EN",
  "active": true,
  "parent": {
    "...": "..."
  }
}

Errors

HTTP Status	Error code	Message
`400`	`40009`	`organization not found`
`400`	`40010`	`malformed URL parameter`
`400`	`4012`	`no organization provided`
`500`	`50002`	`internal server error`

🧑‍🤝‍🧑 Organization members

Path /organizations/{address}/members
Method GET
Response

{
  "members": [
    {
      "info": { /* user info response */ },
      "role": "admin"
    }
  ]
}

Errors

HTTP Status	Error code	Message
`400`	`40009`	`organization not found`
`400`	`40010`	`malformed URL parameter`
`400`	`4012`	`no organization provided`
`500`	`50002`	`internal server error`

🧑‍💼 Invite organization member

Path /organizations/{address}/members
Method POST
Headers
- Authentication: Bearer <user_token>
Request

{
  "role": "admin",
  "email": "newadmin@email.com"
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40002`	`email malformed`
`400`	`40004`	`malformed JSON body`
`400`	`40005`	`invalid user data`
`400`	`40009`	`organization not found`
`400`	`40011`	`no organization provided`
`401`	`40014`	`user account not verified`
`400`	`40019`	`inviation code expired`
`409`	`40901`	`duplicate conflict`
`500`	`50002`	`internal server error`

⏳ List pending invitations

Path /organizations/{address}/members/pending
Method GET
Headers
- Authentication: Bearer <user_token>
Response

{
  "pending": [
    {
      "email": "newuser@email.me",
      "role": "admin",
      "expiration": "2024-12-12T12:00:00.000Z"
    }
  ]
}

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40009`	`organization not found`
`400`	`40011`	`no organization provided`
`401`	`40014`	`user account not verified`
`500`	`50002`	`internal server error`

🤝 Accept organization invitation

Path /organizations/{address}/members/accept
Method POST
Request

{
  "code": "a3f3b5",
  "user": { // only if the invited user is not already registered
    "firstName": "Steve",
    "lastName": "Urkel",
    "password": "secretpass1234"
  }
}

user object is only required if invited user is not registered yet.

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40002`	`email malformed`
`400`	`40004`	`malformed JSON body`
`400`	`40005`	`invalid user data`
`400`	`40009`	`organization not found`
`400`	`40011`	`no organization provided`
`401`	`40014`	`user account not verified`
`400`	`40019`	`inviation code expired`
`409`	`40901`	`duplicate conflict`
`500`	`50002`	`internal server error`

💸 Organization subscription info

Path /organizations/{address}/subscription
Method GET
Request

{
  "subscriptionDetails":{
    "planID":3,
    "startDate":"2024-11-07T15:25:49.218Z",
    "endDate":"0001-01-01T00:00:00Z",
    "renewalDate":"0001-01-01T00:00:00Z",
    "active":true,
    "email": "test@test.com",
    "maxCensusSize":10
  },
  "usage":{
    "sentSMS":0,
    "sentEmails":0,
    "subOrgs":0,
    "members":0
  },
  "plan":{
    "id":3,
    "name":"free",
    "stripeID":"stripe_789",
    "default":true,
    "organization":{
      "memberships":10,
      "subOrgs":5,
      "censusSize":10
    },
    "votingTypes":{
      "approval":false,
      "ranked":false,
      "weighted":true
    },
    "features":{
      "personalization":false,
      "emailReminder":false,
      "smsNotification":false
    }
  }
}

This request can be made only by organization admins.

Errors

HTTP Status	Error code	Message
`401`	`40001`	`user not authorized`
`400`	`40009`	`organization not found`
`400`	`40011`	`no organization provided`
`500`	`50002`	`internal server error`

🤠 Available organization members roles

Path /organizations/roles
Method GET
Response

{
  "roles": [
    {
      "role": "manager",
      "name": "Manager",
      "writePermission": true
    },
    {
      "role": "viewer",
      "name": "Viewer",
      "writePermission": false
    },
    {
      "role": "admin",
      "name": "Admin",
      "writePermission": true
    }
  ]
}

🏛️ Available organization types

Path /organizations/types
Method GET
Response

{
  "types": [
    {
      "type": "cooperative",
      "name": "Cooperative"
    },
    {
      "type": "educational",
      "name": "University / Educational Institution"
    },
    {
      "type": "others",
      "name": "Others"
    },
    {
      "type": "assembly",
      "name": "Assembly"
    },
    {
      "type": "religious",
      "name": "Church / Religious Organization"
    },
    {
      "type": "company",
      "name": "Company / Corporation"
    },
    {
      "type": "political_party",
      "name": "Political Party"
    },
    {
      "type": "chamber",
      "name": "Chamber"
    },
    {
      "type": "nonprofit",
      "name": "Nonprofit / NGO"
    },
    {
      "type": "community",
      "name": "Community Group"
    },
    {
      "type": "professional_college",
      "name": "Professional College"
    },
    {
      "type": "association",
      "name": "Association"
    },
    {
      "type": "city",
      "name": "City / Municipality"
    },
    {
      "type": "union",
      "name": "Union"
    }
  ]
}

🏦 Plans

🛒 Get Plans

Path /plans
Method GET
Response

{
  "plans": [
    {
      "id":1,
      "name":"Basic",
      "stripeID":"stripe_123",
      "startingPrice": "9900",
      "organization":{
        "memberships":1,
        "subOrgs":1
      },
      "votingTypes":{
        "approval":true,
        "ranked":true,
        "weighted":true
      },
      "features":{
        "personalization":false,
        "emailReminder":true,
        "smsNotification":false
      }
    },
     "censusSizeTiers": [
    {
     "flatAmount":9900,
     "upTo":100
    },
    {
     "flatAmount":79900,
     "upTo":1500
    }
  ],
    ...
  ]
}

Errors

HTTP Status	Error code	Message
`500`	`50002`	`internal server error`

🛍️ Get Plan info

Path /plans/{planID}
Method GET
Response

{
  "id":1,
  "name":"Basic",
  "stripeID":"stripe_123",
  "startingPrice": "9900",
  "organization":{
    "memberships":1,
    "subOrgs":1
  },
  "votingTypes":{
    "approval":true,
    "ranked":true,
    "weighted":true
  },
  "features":{
    "personalization":false,
    "emailReminder":true,
    "smsNotification":false
  },
  "censusSizeTiers": [
    {
     "flatAmount":9900,
     "upTo":100
    },
    {
     "flatAmount":79900,
     "upTo":1500
    }
  ],
}

Errors

HTTP Status	Error code	Message
`400`	`40010`	`malformed URL parameter`
`400`	`40023`	`plan not found`
`500`	`50002`	`internal server error`

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs.md

docs.md

API Docs

🔐 Auth

🔑 Login

🥤 Refresh token

💼 User writable organizations addresses

🧾 Transactions

✍️ Sign tx

📝 Sign message

👥 Users

🙋 Register

✅ Verify user

🪪 User verification code info

📤 Resend user verification code

🧑‍💻 Get current user info

💇 Update current user info

🔏 Update current user password

⛓️‍💥 Request a password recovery

🔗 Reset user password

🏤 Organizations

🆕 Create organization

⚙️ Update organization

🔍 Organization info

🧑‍🤝‍🧑 Organization members

🧑‍💼 Invite organization member

⏳ List pending invitations

🤝 Accept organization invitation

💸 Organization subscription info

🤠 Available organization members roles

🏛️ Available organization types

🏦 Plans

🛒 Get Plans

🛍️ Get Plan info

Files

docs.md

Latest commit

History

docs.md

File metadata and controls

API Docs

🔐 Auth

🔑 Login

🥤 Refresh token

💼 User writable organizations addresses

🧾 Transactions

✍️ Sign tx

📝 Sign message

👥 Users

🙋 Register

✅ Verify user

🪪 User verification code info

📤 Resend user verification code

🧑‍💻 Get current user info

💇 Update current user info

🔏 Update current user password

⛓️‍💥 Request a password recovery

🔗 Reset user password

🏤 Organizations

🆕 Create organization

⚙️ Update organization

🔍 Organization info

🧑‍🤝‍🧑 Organization members

🧑‍💼 Invite organization member

⏳ List pending invitations

🤝 Accept organization invitation

💸 Organization subscription info

🤠 Available organization members roles

🏛️ Available organization types

🏦 Plans

🛒 Get Plans

🛍️ Get Plan info