A quick word on API responses

All responses come in a request envelope:

{
  response: { ... },
  meta: {
    code: 400,
    errors: ["Name is required"]
  }
}
response
The target or resulting object. Sometimes a list with additional meta data.
meta.code
For clients that cannot read HTTP status codes.
meta.errors
If you receive 4XX response codes, you can expect an array of errors.
Note: We omit the envelope for brevity when documenting responses.

Data Types

  • IDs are unordered alphanumeric strings.
  • Timestamps are integer seconds since the UNIX epoch.
  • Phone numbers are sent as +<country code> <number>

Format

All data is sent and received as JSON.

While most requests will work as expected with standard HTTP params, it is especially important to send data as JSON in the request body to ensure consistent hash ordering (e.g. when sending multiple members).

Status Codes

We try to return the most appropriate HTTP status code.

Code Text Description
200 OK Success!
201 Created Resource was created successfully.
204 No Content Resource was deleted successfully.
304 Not Modified There was no new data to return.
400 Bad Request Returned when an invalid format or invalid data is specified in the request.
401 Unauthorized Authentication credentials were missing or incorrect.
403 Forbidden The request is understood, but it has been refused. An accompanying error message will explain why. This code is used when requests are being denied due to update limits.
404 Not Found The URI requested is invalid or the resource requested, such as a user, does not exists.
420 Enhance Your Calm Returned when you are being rate limited. Chill the heck out.
500 Internal Server Error Something unexpected occurred. GroupMe will be notified.
502 Bad Gateway GroupMe is down or being upgraded.
503 Service Unavailable The GroupMe servers are up, but overloaded with requests. Try again later.

Questions? Check out our GroupMe API Support Google Group.