# persons

For: READ

The `persons` message type contains information about the persons in the current fixtures. This includes entity players as well as entity roles or fixture (when `entityId` is blank) based roles.

This message is sent whenever an action occurs that causes the information about the people to change. The messages are sent per entity. If the entity field is blank or null, this indicates this data applies to the fixture (not specific entities).

```
{
    "type": "persons",
    "timestamp": "2021-02-03T00:19:40.354050",
    "fixtureId": "0a970bca-fcf1-11e8-8eb2-f2801f1b9fd1",
    "entityId": "2ef78d32-fcf1-11e8-8eb2-f2801f1b9fd1",
    "compressedData": "eJzt3UtzG8cRB/CvktKZTM17ZvcYn3JA2VXRzeUDCCxMxhSWxYdcrpS/ewai5TDYFXoW3cAO6H9VDpEMURS4P8xMTz9+/M+H1f3y6elD+7cPTw/94/OHq7996D532+d/rne/Z2JjmuZmfR03S3+tdbe8TtY310oZ49ZhaWzn//wjH+8+dV/+kNL5FeHa2I/Ktqppdfrfa357+PKap5ebp+e755fnu367+4/511//U//y+l1s83//7fXbUMsmqpvV8nqz2ujdt5GuU3djrjcmKb3RN81mrXd/5qF7fOq3f3zr3SYm15B/5jl/10/Py08Pr9+6UdfKXevwUfnW2Varv+f3QCn7x5e/69dfvrzLv1zd96tfdn/qh49aLdS ... "
}
```

**Bold** fields are required

| Field              | Type   | Description                                                                                                                                                                                                                       |
| ------------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **entityId**       | string | The unique identifier of the entity. If this is blank or null, it indicates that the data is for the fixture, not a specific entity. This would be the case for match official roles such as referees etc or for non-team sports. |
| **compressedData** | string | The `compressedData` key is a base64 encoded zlib compressed JSON string.                                                                                                                                                         |

When uncompressed the data is of the following format.

```
       {
            "entityId": "2ef78d32-fcf1-11e8-8eb2-f2801f1b9fd1",
            "persons": {
                "2ef78c06-fcf1-11e8-8eb2-f2801f1b9fd1": {
                    "name": "Adam Bourke",
                    "active": false
                },
                "665effc2-fcf1-11e8-8eb2-f2801f1b9fd1": {
                    "name": "Mark Smith",
                    "active": true
                },
                ... more persons ...
            },
            "roles": {
                "CAPTAIN": {
                    "2ef78c06-fcf1-11e8-8eb2-f2801f1b9fd1": {
                        "name": "Adam Bourke"
                    }
                },
                "COACH": {
                    "98743232-fcf1-11e8-8eb2-f2801f1b9fd1": {
                        "number": 1,
                        "name": "Anthony Jones"
                    }
                }
            }
        }
    
```

**Bold** fields are required

| Field                  | Type    | Description                                                                                                                                    |
| ---------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| entityId               | string  | Unique identifier for the entity that this data relates to. If this is blank or not present, it indicates this data is for the entire fixture. |
| persons                | object  | An object containing information about the players in the entity                                                                               |
| persons.X              | object  | An object containing information about a specific player.                                                                                      |
| persons.X.name         | string  | The name of the person. This is just a basic name, more information can be obtained from the REST APi.                                         |
| persons.X.position     | string  | The position this person plays.                                                                                                                |
| persons.X.bib          | string  | The number/position on this player's bib/shirt                                                                                                 |
| persons.X.active       | boolean | Whether this person is currently on the field of play                                                                                          |
| persons.X.starter      | boolean | Whether this person was on the field of play at the start of the fixture.                                                                      |
| persons.X.unregistered | boolean | Is this person un-registered?                                                                                                                  |
| roles                  | object  | An object containing information about the roles in the entity                                                                                 |
| roles.X                | object  | An object containing information about a specific role.                                                                                        |
| roles.X.name           | string  | The name of the person. This is just a basic name, more information can be obtained from the REST APi.                                         |
| roles.X.bib            | string  | The number/position on this person's bib/shirt                                                                                                 |
| roles.X.number         | integer | The official's number, eg 2nd referee                                                                                                          |

If a field has no value then the key/value will not be sent as part of the message.